├── assets
    ├── coin.animation.yml
    ├── coin.png
    └── README.md
├── .gitignore
├── .github
    └── workflows
    │   ├── create-release.yml
    │   └── check.yml
├── .cargo
    └── fast_compiles_config
├── release.toml
├── renovate.json
├── Cargo.toml
├── LICENSE-MIT
├── UNLICENSE
├── CHANGELOG.md
├── justfile
├── src
    ├── lib.rs
    ├── animation
    │   ├── mod.rs
    │   └── dto.rs
    └── state.rs
├── examples
    └── bevy.rs
├── README.md
└── CONTRIBUTING.md


/assets/coin.animation.yml:
--------------------------------------------------------------------------------
1 | mode: Repeat
2 | fps: 12
3 | frames: [0, 1, 2, 3, 4]
4 | 


--------------------------------------------------------------------------------
/assets/coin.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/jcornaz/benimator/HEAD/assets/coin.png


--------------------------------------------------------------------------------
/assets/README.md:
--------------------------------------------------------------------------------
1 | # Credits
2 | 
3 | Coin by [La Red Games](https://laredgames.itch.io/gems-coins-free) (CC0)
4 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | # Rust
 2 | /target
 3 | /Cargo.lock
 4 | /.cargo/*.toml
 5 | 
 6 | # IDE
 7 | /.idea
 8 | /.vscode
 9 | *.iml
10 | 
11 | # Operating systems
12 | .DS_Store
13 | .trashes
14 | *.db
15 | 
16 | # Nodes tools
17 | /node_modules
18 | 


--------------------------------------------------------------------------------
/.github/workflows/create-release.yml:
--------------------------------------------------------------------------------
 1 | name: Create github release
 2 | 
 3 | permissions:
 4 |   contents: write
 5 | 
 6 | on:
 7 |   push:
 8 |     tags:
 9 |       - v[0-9]+.*
10 | 
11 | jobs:
12 |   create-release:
13 |     runs-on: ubuntu-latest
14 |     steps:
15 |       - uses: actions/checkout@v4
16 |       - uses: taiki-e/create-gh-release-action@v1
17 |         with:
18 |           changelog: CHANGELOG.md
19 |           token: ${{ github.token }}
20 | 


--------------------------------------------------------------------------------
/.cargo/fast_compiles_config:
--------------------------------------------------------------------------------
 1 | # Copy the content of this file to `.cargo/config.toml`
 2 | 
 3 | [target.x86_64-unknown-linux-gnu]
 4 | linker = "clang"
 5 | rustflags = ["-Clink-arg=-fuse-ld=lld"]
 6 | 
 7 | [target.x86_64-apple-darwin]
 8 | rustflags = ["-C", "link-arg=-fuse-ld=/usr/local/bin/zld"]
 9 | 
10 | [target.aarch64-apple-darwin]
11 | rustflags = ["-C", "link-arg=-fuse-ld=/opt/homebrew/bin/zld"]
12 | 
13 | [target.x86_64-pc-windows-msvc]
14 | linker = "rust-lld.exe"
15 | 
16 | [target.wasm32-unknown-unknown]
17 | runner = "wasm-server-runner"
18 | 


--------------------------------------------------------------------------------
/.github/workflows/check.yml:
--------------------------------------------------------------------------------
 1 | name: check
 2 | 
 3 | on:
 4 |   push:
 5 |     branches: ["[0-9]+.x", main, rc, beta, alpha]
 6 |   pull_request:
 7 |   workflow_dispatch:
 8 | 
 9 | jobs:
10 |   verify:
11 |     runs-on: ubuntu-24.04
12 |     timeout-minutes: 10
13 |     steps:
14 |       - uses: actions/checkout@v4
15 |       - uses: dtolnay/rust-toolchain@stable
16 |         with:
17 |           components: clippy, rustfmt
18 |       - uses: Swatinem/rust-cache@v2
19 |       - uses: taiki-e/install-action@v2
20 |         with:
21 |           tool: cargo-hack@0.5,just@1,cargo-msrv@0.16
22 |       - run: just verify
23 | 


--------------------------------------------------------------------------------
/release.toml:
--------------------------------------------------------------------------------
 1 | allow-branch = ["main"]
 2 | pre-release-commit-message = "release {{version}}"
 3 | 
 4 | [[pre-release-replacements]]
 5 | file = "CHANGELOG.md"
 6 | search = "## \\[Unreleased\\]"
 7 | replace = "## [Unreleased]\n\n\n## [{{version}}] - {{date}}"
 8 | prerelease = true
 9 | exactly = 1
10 | 
11 | [[pre-release-replacements]]
12 | file = "CHANGELOG.md"
13 | search = "\\.\\.\\.HEAD"
14 | replace = "...v{{version}}"
15 | prerelease = true
16 | exactly = 1
17 | 
18 | [[pre-release-replacements]]
19 | file = "CHANGELOG.md"
20 | search = "\\[Unreleased\\]:"
21 | replace = "[Unreleased]: https://github.com/jcornaz/beancount-parser/compare/v{{version}}...HEAD\n[{{version}}]:"
22 | prerelease = true
23 | exactly = 1
24 | 


--------------------------------------------------------------------------------
/renovate.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
 3 |   "extends": ["config:recommended"],
 4 |   "timezone": "Europe/Zurich",
 5 |   "schedule": ["after 10pm", "before 5:00am"],
 6 |   "packageRules": [
 7 |     {
 8 |       "matchPackageNames": "bevy",
 9 |       "enabled": false
10 |     },
11 |     {
12 |       "matchCurrentVersion": ">=1.0.0",
13 |       "matchUpdateTypes": [
14 |         "minor",
15 |         "patch"
16 |       ],
17 |       "automerge": true
18 |     },
19 |     {
20 |       "matchCurrentVersion": ">=0.1.0 <1.0.0",
21 |       "matchUpdateTypes": [
22 |         "patch"
23 |       ],
24 |       "automerge": true
25 |     },
26 |     {
27 |       "matchDepTypes": [
28 |         "dev-dependencies"
29 |       ],
30 |       "automerge": true
31 |     }
32 |   ]
33 | }
34 | 


--------------------------------------------------------------------------------
/Cargo.toml:
--------------------------------------------------------------------------------
 1 | [package]
 2 | name = "benimator"
 3 | version = "4.1.3"
 4 | edition = "2021"
 5 | rust-version = "1.70"
 6 | authors = ["Jonathan Cornaz"]
 7 | license = "Unlicense OR MIT"
 8 | description = "A sprite animation library for rust game development"
 9 | repository = "https://github.com/jcornaz/benimator"
10 | keywords = ["game", "gamedev", "anmiation"]
11 | categories = ["game-development"]
12 | 
13 | [package.metadata.docs.rs]
14 | all-features = true
15 | 
16 | [features]
17 | default = []
18 | 
19 | [dependencies]
20 | # Public dependencies (Present in the public API)
21 | serde = { version = "1.0.200", features = ["derive"], optional = true }
22 | 
23 | [dev-dependencies]
24 | serde_yaml = { version = "0.9.34", default-features = false }
25 | rstest = { version = "0.21.0", default-features = false }
26 | bevy = { version = "0.12.1", default-features = false, features = ["bevy_asset", "bevy_winit", "bevy_render", "bevy_sprite", "bevy_core_pipeline", "png", "x11", "dynamic_linking"] }
27 | anyhow = "1.0.82"
28 | toml = "0.8.12"
29 | 
30 | [build-dependencies]
31 | rustc_version = "0.4.0"
32 | 
33 | 


--------------------------------------------------------------------------------
/LICENSE-MIT:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2021 Jonathan Cornaz
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/UNLICENSE:
--------------------------------------------------------------------------------
 1 | This is free and unencumbered software released into the public domain.
 2 | 
 3 | Anyone is free to copy, modify, publish, use, compile, sell, or
 4 | distribute this software, either in source code form or as a compiled
 5 | binary, for any purpose, commercial or non-commercial, and by any
 6 | means.
 7 | 
 8 | In jurisdictions that recognize copyright laws, the author or authors
 9 | of this software dedicate any and all copyright interest in the
10 | software to the public domain. We make this dedication for the benefit
11 | of the public at large and to the detriment of our heirs and
12 | successors. We intend this dedication to be an overt act of
13 | relinquishment in perpetuity of all present and future rights to this
14 | software under copyright law.
15 | 
16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19 | IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
20 | OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
21 | ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22 | OTHER DEALINGS IN THE SOFTWARE.
23 | 
24 | For more information, please refer to <http://unlicense.org/>
25 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | # Changelog
 2 | 
 3 | All notable changes to this project will be documented in this file.
 4 | 
 5 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 6 | 
 7 | 
 8 | ## [Unreleased]
 9 | 
10 | ### Dependencies
11 | 
12 | * Minimum supported rust version raised to `1.70`
13 | 
14 | 
15 | ## [4.1.3] - 2023-07-01
16 | 
17 | ### Bug fixes
18 | 
19 | * Fixed deserialization error of a "short form" frame list when using the toml crate.
20 | 
21 | 
22 | ### Thank you
23 | 
24 | * @tguichaoua
25 | 
26 | 
27 | ## [4.1.2](https://github.com/jcornaz/benimator/compare/v4.1.1...v4.1.2) (2023-01-09)
28 | 
29 | 
30 | ### Documentation
31 | 
32 | * **readme:** lower minimum support rust version to 1.60 ([909eaea](https://github.com/jcornaz/benimator/commit/909eaea4b8974872126961c2be0650aa5e3e5b85))
33 | 
34 | ## [4.1.1](https://github.com/jcornaz/benimator/compare/v4.1.0...v4.1.1) (2023-01-08)
35 | 
36 | 
37 | ### Documentation
38 | 
39 | * **readme:** fix build badge ([6ee96e7](https://github.com/jcornaz/benimator/commit/6ee96e719de6cef82eb04d4ca86e11cef3e011a1))
40 | * **readme:** remove build status badge ([dd9adc9](https://github.com/jcornaz/benimator/commit/dd9adc9aa0b4d47c7eabcfcbf954f9bc9e2e4ca7))
41 | 
42 | 
43 | [Unreleased]: https://github.com/jcornaz/beancount-parser/compare/v4.1.3...HEAD
44 | [4.1.3]: https://github.com/jcornaz/benimator/compare/v4.1.2...v4.1.3
45 | 
46 | 


--------------------------------------------------------------------------------
/justfile:
--------------------------------------------------------------------------------
 1 | set dotenv-load
 2 | 
 3 | @_choose:
 4 | 	just --choose --unsorted
 5 | 
 6 | # Perform all verifications (compile, test, lint, etc.)
 7 | verify: test lint doc check-msrv
 8 | 
 9 | # Watch the source files and run `just verify` when source changes
10 | watch:
11 | 	cargo watch --delay 0.1 --clear --why -- just verify
12 | 
13 | # Run the tests
14 | test:
15 | 	cargo hack test --feature-powerset --optional-deps
16 | 
17 | # Run the static code analysis
18 | lint:
19 | 	cargo fmt -- --check
20 | 	cargo hack clippy --feature-powerset --all-targets --optional-deps
21 | 
22 | # Build the documentation
23 | doc *args:
24 | 	cargo doc --all-features --no-deps {{args}}
25 | 
26 | # Open the documentation page
27 | doc-open: (doc "--open")
28 | 
29 | # Run the given example
30 | run example:
31 |     cargo run --all-features --example {{example}}
32 | 
33 | # Make sure the MSRV is satisfiable
34 | check-msrv:
35 | 	cargo msrv verify
36 | 
37 | # Clean up compilation output
38 | clean:
39 | 	rm -rf target
40 | 	rm -f Cargo.lock
41 | 	rm -rf node_modules
42 | 
43 | # Install cargo dev-tools used by the `verify` recipe (requires rustup to be already installed)
44 | install-dev-tools:
45 | 	rustup install stable
46 | 	rustup override set stable
47 | 	cargo install cargo-hack cargo-watch cargo-msrv
48 | 
49 | # Install a git hook to run tests before every commits
50 | install-git-hooks:
51 | 	echo '#!/usr/bin/env sh' > .git/hooks/pre-commit
52 | 	echo 'just verify' >> .git/hooks/pre-commit
53 | 	chmod +x .git/hooks/pre-commit
54 | 
55 | release *args: verify
56 | 	cargo release {{args}}
57 | 


--------------------------------------------------------------------------------
/src/lib.rs:
--------------------------------------------------------------------------------
 1 | #![warn(
 2 |     future_incompatible,
 3 |     nonstandard_style,
 4 |     rust_2018_idioms,
 5 |     missing_docs,
 6 |     clippy::pedantic
 7 | )]
 8 | #![cfg_attr(test, allow(clippy::needless_pass_by_value))]
 9 | #![cfg_attr(nightly, feature(doc_auto_cfg))]
10 | 
11 | //! A sprite animation library for rust game development
12 | //!
13 | //! Initially designed for [bevy], it is now engine agnostic.                       
14 | //!
15 | //! # Get started
16 | //!
17 | //! benimator assumes usage of texture atlas (or equivalent).
18 | //!
19 | //! An [`Animation`] contains the list of animation frames,
20 | //! each frame defined by an index.
21 | //!
22 | //! ```
23 | //! # use std::time::Duration;
24 | //! use benimator::*;
25 | //!
26 | //! // Create an animation
27 | //! let animation = Animation::from_indices(0..=3, FrameRate::from_fps(10.0));
28 | //!
29 | //! // Create a new animation state
30 | //! let mut state = State::new();
31 | //!
32 | //! // In the game loop, for each update, tell the state how much time has elapsed
33 | //! let delta_time = Duration::from_millis(250);
34 | //! state.update(&animation, delta_time);
35 | //!
36 | //! // Then get the current frame index.
37 | //! // (so that we can tell our engine to render the sprite at that index)
38 | //! assert_eq!(state.frame_index(), 2);
39 | //! ```
40 | //!
41 | //! Have a look at the [examples](https://github.com/jcornaz/benimator/tree/main/examples) for complete examples using the [bevy] game engine.
42 | //!
43 | //! [bevy]: https://bevyengine.org
44 | 
45 | #[cfg(test)]
46 | #[macro_use]
47 | extern crate rstest;
48 | 
49 | pub use animation::{Animation, Frame, FrameRate};
50 | pub use state::State;
51 | 
52 | mod animation;
53 | mod state;
54 | 


--------------------------------------------------------------------------------
/examples/bevy.rs:
--------------------------------------------------------------------------------
 1 | use bevy::prelude::*;
 2 | 
 3 | use benimator::FrameRate;
 4 | 
 5 | // Create the animation component
 6 | // Note: you may make the animation an asset instead of a component
 7 | #[derive(Component, Deref)]
 8 | struct Animation(benimator::Animation);
 9 | 
10 | // Create the player component
11 | #[derive(Default, Component, Deref, DerefMut)]
12 | struct AnimationState(benimator::State);
13 | 
14 | fn main() {
15 |     App::new()
16 |         .add_plugins(DefaultPlugins.set(ImagePlugin::default_nearest()))
17 |         .add_systems(Startup, spawn)
18 |         .add_systems(Update, animate)
19 |         .run();
20 | }
21 | 
22 | fn spawn(
23 |     mut commands: Commands,
24 |     asset_server: Res<AssetServer>,
25 |     mut textures: ResMut<Assets<TextureAtlas>>,
26 | ) {
27 |     // Don't forget the camera ;-)
28 |     commands.spawn(Camera2dBundle::default());
29 | 
30 |     // Create an animation
31 |     let animation = Animation(benimator::Animation::from_indices(
32 |         0..=4,
33 |         FrameRate::from_fps(12.0),
34 |     ));
35 | 
36 |     commands
37 |         // Spawn a bevy sprite-sheet
38 |         .spawn(SpriteSheetBundle {
39 |             texture_atlas: textures.add(TextureAtlas::from_grid(
40 |                 asset_server.load("coin.png"),
41 |                 Vec2::new(16.0, 16.0),
42 |                 5,
43 |                 1,
44 |                 None,
45 |                 None,
46 |             )),
47 |             transform: Transform::from_scale(Vec3::splat(10.0)),
48 |             ..Default::default()
49 |         })
50 |         // Insert the animation
51 |         .insert(animation)
52 |         // Insert the state
53 |         .insert(AnimationState::default());
54 | }
55 | 
56 | fn animate(
57 |     time: Res<Time>,
58 |     mut query: Query<(&mut AnimationState, &mut TextureAtlasSprite, &Animation)>,
59 | ) {
60 |     for (mut player, mut texture, animation) in query.iter_mut() {
61 |         // Update the state
62 |         player.update(animation, time.delta());
63 | 
64 |         // Update the texture atlas
65 |         texture.index = player.frame_index();
66 |     }
67 | }
68 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Benimator
 2 | 
 3 | [![License](https://img.shields.io/crates/l/benimator)](#License)
 4 | [![Crates.io](https://img.shields.io/crates/v/benimator)](https://crates.io/crates/benimator)
 5 | ![rustc](https://img.shields.io/badge/rustc-1.70+-blue?logo=rust)
 6 | [![Docs](https://docs.rs/benimator/badge.svg)](https://docs.rs/benimator)
 7 | ![Maintenance](https://img.shields.io/maintenance/no/2025)
 8 | 
 9 | A sprite animation library for rust game development.
10 | 
11 | Initially designed for [bevy], it is now engine agnostic.
12 | 
13 | ## Status
14 | 
15 | This project is discontinued.
16 | 
17 | ## Goals
18 | 
19 | This project aim to provide the building the blocks to facilitate 2d sprite animation
20 | with any game engine.
21 | 
22 | ## Non-goals
23 | 
24 | Benimator is not rendering anything. It only keeps track of sprite indices.
25 | 
26 | One is expected to use benimator with a game engine such as [bevy].
27 | 
28 | [bevy]: https://bevyengine.org
29 | 
30 | ## How it looks like
31 | 
32 | At its core benimator is an `Animation` data structure
33 | and a `State` to track the frame-index as time pass.
34 | 
35 | ```rust
36 | // Create an animation
37 | let animation = Animation::from_indices(0..=3, FrameRate::from_fps(10.0));
38 | 
39 | // Create a new animation state
40 | let mut state = State::new();
41 | 
42 | // In the game loop, for each update, tell the state how much time has elapsed
43 | let delta_time = Duration::from_millis(250);
44 | state.update(&animation, delta_time);
45 | 
46 | // Then get the current frame index.
47 | // (so that we can tell our engine to render the sprite at that index)
48 | assert_eq!(state.frame_index(), 2);
49 | ```
50 | 
51 | Have a look at the [examples](https://github.com/jcornaz/benimator/tree/main/examples) for complete examples using the [bevy] game engine.
52 | 
53 | ## Installation
54 | 
55 | benimator is published on [crates.io](https://crates.io/crates/benimator)
56 | 
57 | You can add the dependency to your cargo file with:
58 | 
59 | ```sh
60 | cargo add benimator
61 | ```
62 | 
63 | ## Cargo features
64 | 
65 | | Feature | Description                                      |
66 | |---------|--------------------------------------------------|
67 | | `serde` | Implementations of `Serialize` and `Deserialize` |
68 | 
69 | *Feature flags not mentioned here are **NOT** part of the public API and are subject to breaking changes!*
70 | 
71 | ## MSRV
72 | 
73 | The minimum supported rust version is currently `1.70`.
74 | 
75 | It can be updated to a newer stable version when required, and that will not be considered a breaking change (it can happen in for a minor or patch release).
76 | 
77 | ## License
78 | 
79 | Licensed under either of
80 | 
81 | * The Unlicense ([UNLICENSE](UNLICENSE) or https://opensource.org/licenses/Unlicense)
82 | * MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
83 | 
84 | at your option.
85 | 


--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
 1 | # How to contribute
 2 | 
 3 | ## Ask for help, propose a feature request a feature or report a bug
 4 | 
 5 | Feel free to create an [issue](https://github.com/jcornaz/benimator/issues) or open a [discussion](https://github.com/jcornaz/benimator/discussions)
 6 | 
 7 | 
 8 | ## Choose an issue to work on
 9 | 
10 | You don't *need* to find an open issue to contribute a PR. But it is better to make sure the change is actually desirable.
11 | 
12 | I assign myself to issues when I am working on them. So you can safely pick any
13 | [unassigned issue](https://github.com/jcornaz/benimator/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+no%3Aassignee+).
14 | 
15 | You may (but don't have to) write a message in the issue to say you are working on it.
16 | 
17 | ## Build from source
18 | 
19 | Run the tests
20 | ```sh
21 | cargo test --all-features
22 | ```
23 | 
24 | Check code style
25 | ```
26 | cargo fmt
27 | cargo clippy --all-targets --all-features
28 | ```
29 | 
30 | Build (and open) documentation
31 | ```
32 | cargo doc --no-deps --all-features --open
33 | ```
34 | 
35 | ## Coding standards
36 | 
37 | ### Tests
38 | 
39 | This is a test-driven project. Every new feature and bug fixes must come with tests.
40 | If you need help to test your feature or fix, you can ask in a draft PR, and I'll do my best to help you.
41 | 
42 | ### API stability
43 | 
44 | #### Add stable API
45 | 
46 | When writting new code make sure you don't expose any unecessary technical detail:
47 | * Never expose struct fields!
48 | * Use `#[non_exhaustive]` for enums and unit structs
49 | * Be very carefull with public enums. In doubt keep them private.
50 | * Don't expose types and functions that do no need to be public
51 | * Don't eagerly implement traits that are not yet needed or related to the use-case
52 |   * except for `Debug`, `Clone`, `Eq`, `PartialEq` and `Default` that may be implemented eagerly when it makes sense
53 |   * note that if a `new()` constuctor does not make sense, `Default` should **not** be implemented
54 |   * in case of doubt, don't implement what you don't need, don't worry we can add it later
55 | * Avoid promissing too much in return types. (e.g. `&[T]` are better that `&Vec<T>`)
56 | 
57 | New API may be gated behind a `unstable-` cargo flag until it is stabilized.
58 | 
59 | #### Do not break existing API
60 | 
61 | Do not break public API. (See https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md to understand what constitute a breaking change)
62 | 
63 | Instead create a new API. Eventually we may deprecate the old one and hide it from the doc.
64 | 
65 | The API may eventually be broken (in a new major version). But I want to avoid that for as long as possible (forever would be perfect).
66 | I see a breaking change as good only if it makes future breaking changes less likely to be needed. 
67 | For example, to make struct field privates is a an acceptable breaking change.
68 | 
69 | If you don't see how to improve an API without breaking it, you can start a discussion in the issues.
70 | 
71 | ## Open a pull request
72 | 
73 | Don't be afraid of small steps. I'd rather review 5 tiny pull-requests than 1 big.
74 | 
75 | But to be merged a pull-request needs to be in state ready for release:
76 | * New features and Bug fixes must comes with automated tests
77 | * The build must pass
78 | * The documentation must be up-to-date
79 | 


--------------------------------------------------------------------------------
/src/animation/mod.rs:
--------------------------------------------------------------------------------
  1 | use core::time::Duration;
  2 | 
  3 | #[cfg(feature = "serde")]
  4 | use serde::{Deserialize, Serialize};
  5 | 
  6 | #[cfg(feature = "serde")]
  7 | mod dto;
  8 | 
  9 | /// Definition of an animation
 10 | #[cfg_attr(
 11 |     feature = "serde",
 12 |     doc = "
 13 | 
 14 | # Deserialization format
 15 |  
 16 | ```yaml
 17 | # The mode can be one of: 'Once', 'Repeat', 'PingPong'
 18 | # or '!RepeatFrom: n' (where 'n' is the frame-index to repeat from)
 19 | # The default is 'Repeat'
 20 | mode: PingPong
 21 | frames:
 22 |   - index: 0 # index in the sprite sheet for that frame
 23 |     duration: 100 # duration of the frame in milliseconds
 24 |   - index: 1
 25 |     duration: 100
 26 |   - index: 2
 27 |     duration: 120
 28 | ```
 29 | 
 30 | There is also a short-hand notation if all frames have the same duration:
 31 | 
 32 | ```yaml
 33 | fps: 12 # may be substitued by 'frame_duration' of 'total_duration'
 34 | frames: [0, 1, 2] # sequence of frame indices
 35 | ```
 36 | "
 37 | )]
 38 | #[derive(Debug, Clone, Eq, PartialEq)]
 39 | #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 40 | #[cfg_attr(
 41 |     feature = "serde",
 42 |     serde(try_from = "dto::AnimationDto", into = "dto::AnimationDto")
 43 | )]
 44 | pub struct Animation {
 45 |     /// Frames
 46 |     pub(crate) frames: Vec<Frame>,
 47 |     /// Animation mode
 48 |     pub(crate) mode: Mode,
 49 | }
 50 | 
 51 | /// A single animation frame
 52 | #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 53 | pub struct Frame {
 54 |     /// Index in the sprite atlas
 55 |     pub(crate) index: usize,
 56 |     /// How long should the frame be displayed
 57 |     pub(crate) duration: Duration,
 58 | }
 59 | 
 60 | impl Animation {
 61 |     /// Create a new animation from frames
 62 |     #[must_use]
 63 |     pub fn from_frames(frames: impl IntoIterator<Item = Frame>) -> Self {
 64 |         Self {
 65 |             frames: frames.into_iter().collect(),
 66 |             mode: Mode::default(),
 67 |         }
 68 |     }
 69 | 
 70 |     /// Create a new animation from an index iterator, using the same frame duration for each frame.
 71 |     ///
 72 |     /// # Examples
 73 |     ///
 74 |     /// ```
 75 |     /// # use benimator::{Animation, FrameRate};
 76 |     /// # use std::time::Duration;
 77 |     /// // From an index range
 78 |     /// let animation = Animation::from_indices(0..=5, FrameRate::from_fps(12.0));
 79 |     ///
 80 |     /// // From an index array
 81 |     /// let animation = Animation::from_indices([1, 2, 3, 4], FrameRate::from_fps(12.0));
 82 |     ///
 83 |     /// // Reversed animation
 84 |     /// let animation = Animation::from_indices((0..5).rev(), FrameRate::from_fps(12.0));
 85 |     ///
 86 |     /// // Chained ranges
 87 |     /// let animation = Animation::from_indices((0..3).chain(10..15), FrameRate::from_fps(12.0));
 88 |     /// ```
 89 |     ///
 90 |     /// Note, the [`FrameRate`] may be created from fps, frame-duration and animation-duration
 91 |     ///
 92 |     /// To use different non-uniform frame-duration, see [`from_frames`](Animation::from_frames)
 93 |     ///
 94 |     /// # Panics
 95 |     ///
 96 |     /// Panics if the duration is zero
 97 |     pub fn from_indices(indices: impl IntoIterator<Item = usize>, frame_rate: FrameRate) -> Self {
 98 |         let mut anim: Self = indices
 99 |             .into_iter()
100 |             .map(|index| Frame::new(index, frame_rate.frame_duration))
101 |             .collect();
102 | 
103 |         if frame_rate.is_total_duration {
104 |             #[allow(clippy::cast_precision_loss)]
105 |             let actual_duration = frame_rate.frame_duration.div_f64(anim.frames.len() as f64);
106 |             for frame in &mut anim.frames {
107 |                 frame.duration = actual_duration;
108 |             }
109 |         }
110 | 
111 |         anim
112 |     }
113 | 
114 |     /// Runs the animation once and then stop playing
115 |     #[must_use]
116 |     pub fn once(mut self) -> Self {
117 |         self.mode = Mode::Once;
118 |         self
119 |     }
120 | 
121 |     /// Repeat the animation forever
122 |     #[must_use]
123 |     pub fn repeat(mut self) -> Self {
124 |         self.mode = Mode::RepeatFrom(0);
125 |         self
126 |     }
127 | 
128 |     /// Repeat the animation forever, from a given frame index (loop back to it at the end of the
129 |     /// animation)
130 |     #[must_use]
131 |     pub fn repeat_from(mut self, frame_index: usize) -> Self {
132 |         self.mode = Mode::RepeatFrom(frame_index);
133 |         self
134 |     }
135 | 
136 |     /// Repeat the animation forever, going back and forth between the first and last frame.
137 |     #[must_use]
138 |     pub fn ping_pong(mut self) -> Self {
139 |         self.mode = Mode::PingPong;
140 |         self
141 |     }
142 | 
143 |     pub(crate) fn has_frames(&self) -> bool {
144 |         !self.frames.is_empty()
145 |     }
146 | }
147 | 
148 | #[derive(Debug, Copy, Clone, Eq, PartialEq)]
149 | pub(crate) enum Mode {
150 |     Once,
151 |     RepeatFrom(usize),
152 |     PingPong,
153 | }
154 | 
155 | impl FromIterator<Frame> for Animation {
156 |     fn from_iter<T: IntoIterator<Item = Frame>>(iter: T) -> Self {
157 |         Self::from_frames(iter)
158 |     }
159 | }
160 | 
161 | impl Extend<Frame> for Animation {
162 |     fn extend<T: IntoIterator<Item = Frame>>(&mut self, iter: T) {
163 |         self.frames.extend(iter);
164 |     }
165 | }
166 | 
167 | impl Default for Mode {
168 |     #[inline]
169 |     fn default() -> Self {
170 |         Self::RepeatFrom(0)
171 |     }
172 | }
173 | 
174 | impl Frame {
175 |     /// Create a new animation frame
176 |     ///
177 |     /// The duration must be > 0
178 |     ///
179 |     /// # Panics
180 |     ///
181 |     /// Panics if the duration is zero
182 |     #[inline]
183 |     #[must_use]
184 |     pub fn new(index: usize, duration: Duration) -> Self {
185 |         assert!(
186 |             !duration.is_zero(),
187 |             "zero-duration is invalid for animation frame"
188 |         );
189 |         Self { index, duration }
190 |     }
191 | }
192 | 
193 | /// Frame-Rate definition
194 | #[derive(Debug, Copy, Clone, Eq, PartialEq)]
195 | #[must_use]
196 | pub struct FrameRate {
197 |     frame_duration: Duration,
198 |     is_total_duration: bool,
199 | }
200 | 
201 | impl FrameRate {
202 |     /// Frame rate defined by the FPS (Frame-Per-Second)
203 |     ///
204 |     /// # Panics
205 |     ///
206 |     /// This function will panic if `fps` is negative, zero or not finite.
207 |     pub fn from_fps(fps: f64) -> Self {
208 |         assert!(fps.is_finite() && fps > 0.0, "Invalid FPS: ${fps}");
209 |         Self {
210 |             frame_duration: Duration::from_secs(1).div_f64(fps),
211 |             is_total_duration: false,
212 |         }
213 |     }
214 | 
215 |     /// Frame rate defined by the duration of each frame
216 |     pub fn from_frame_duration(duration: Duration) -> Self {
217 |         Self {
218 |             frame_duration: duration,
219 |             is_total_duration: false,
220 |         }
221 |     }
222 | 
223 |     /// Frame rate defined by the total duration of the animation
224 |     ///
225 |     /// The actual FPS will then depend on the number of frame
226 |     pub fn from_total_duration(duration: Duration) -> Self {
227 |         Self {
228 |             frame_duration: duration,
229 |             is_total_duration: true,
230 |         }
231 |     }
232 | }
233 | 
234 | #[cfg(test)]
235 | #[allow(clippy::should_panic_without_expect)]
236 | mod tests {
237 |     use super::*;
238 | 
239 |     #[rstest]
240 |     #[should_panic]
241 |     fn invalid_frame_rate_panics(#[values(0.0, -1.0, f64::NAN, f64::INFINITY)] fps: f64) {
242 |         let _ = FrameRate::from_fps(fps);
243 |     }
244 | 
245 |     #[test]
246 |     #[should_panic]
247 |     fn panics_for_zero_duration() {
248 |         let _ = Frame::new(0, Duration::ZERO);
249 |     }
250 | 
251 |     #[test]
252 |     fn extends() {
253 |         let mut anim = Animation::from_indices(
254 |             0..=0,
255 |             FrameRate::from_frame_duration(Duration::from_secs(1)),
256 |         );
257 |         anim.extend([Frame::new(2, Duration::from_secs(2))]);
258 |         assert_eq!(
259 |             anim,
260 |             Animation::from_frames(vec![
261 |                 Frame::new(0, Duration::from_secs(1)),
262 |                 Frame::new(2, Duration::from_secs(2))
263 |             ])
264 |         );
265 |     }
266 | 
267 |     #[test]
268 |     fn fps_frame_duration_equivalence() {
269 |         assert_eq!(
270 |             Animation::from_indices(1..=3, FrameRate::from_fps(10.0)),
271 |             Animation::from_indices(
272 |                 1..=3,
273 |                 FrameRate::from_frame_duration(Duration::from_millis(100))
274 |             ),
275 |         );
276 |     }
277 | 
278 |     #[test]
279 |     fn total_duration() {
280 |         assert_eq!(
281 |             Animation::from_indices(
282 |                 0..10,
283 |                 FrameRate::from_total_duration(Duration::from_secs(1))
284 |             ),
285 |             Animation::from_indices(
286 |                 0..10,
287 |                 FrameRate::from_frame_duration(Duration::from_millis(100))
288 |             ),
289 |         );
290 |     }
291 | }
292 | 


--------------------------------------------------------------------------------
/src/animation/dto.rs:
--------------------------------------------------------------------------------
  1 | use std::{
  2 |     error::Error,
  3 |     fmt::{self, Display, Formatter},
  4 |     time::Duration,
  5 | };
  6 | 
  7 | use serde::{
  8 |     de::{self, value::MapAccessDeserializer, MapAccess, Unexpected},
  9 |     Deserialize, Serialize,
 10 | };
 11 | 
 12 | use super::{Animation, Frame, Mode};
 13 | 
 14 | #[derive(Serialize, Deserialize)]
 15 | pub(super) struct AnimationDto {
 16 |     #[serde(default)]
 17 |     mode: ModeDto,
 18 |     #[serde(default, skip_serializing)]
 19 |     frame_duration: Option<u64>,
 20 |     #[serde(default, skip_serializing)]
 21 |     fps: Option<u64>,
 22 |     #[serde(default, skip_serializing)]
 23 |     total_duration: Option<u64>,
 24 |     frames: Vec<FrameDto>,
 25 | }
 26 | 
 27 | #[derive(Serialize, Deserialize, Default)]
 28 | enum ModeDto {
 29 |     #[default]
 30 |     Repeat,
 31 |     RepeatFrom(usize),
 32 |     Once,
 33 |     PingPong,
 34 | }
 35 | 
 36 | #[derive(Serialize)]
 37 | struct FrameDto {
 38 |     index: usize,
 39 |     duration: Option<u64>,
 40 | }
 41 | 
 42 | impl<'de> Deserialize<'de> for FrameDto {
 43 |     fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
 44 |     where
 45 |         D: serde::Deserializer<'de>,
 46 |     {
 47 |         struct Visitor;
 48 | 
 49 |         #[derive(Deserialize)]
 50 |         #[serde(deny_unknown_fields)]
 51 |         struct FrameDtoMap {
 52 |             index: usize,
 53 |             duration: Option<u64>,
 54 |         }
 55 | 
 56 |         impl<'de> de::Visitor<'de> for Visitor {
 57 |             type Value = FrameDto;
 58 | 
 59 |             fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
 60 |                 write!(formatter, "either a frame index, or a frame-index with a")
 61 |             }
 62 | 
 63 |             fn visit_u64<E>(self, v: u64) -> Result<Self::Value, E>
 64 |             where
 65 |                 E: de::Error,
 66 |             {
 67 |                 v.try_into()
 68 |                     .map(|index| FrameDto {
 69 |                         index,
 70 |                         duration: None,
 71 |                     })
 72 |                     .map_err(|_| de::Error::invalid_value(Unexpected::Unsigned(v), &self))
 73 |             }
 74 | 
 75 |             fn visit_i64<E>(self, v: i64) -> Result<Self::Value, E>
 76 |             where
 77 |                 E: de::Error,
 78 |             {
 79 |                 v.try_into()
 80 |                     .map(|index| FrameDto {
 81 |                         index,
 82 |                         duration: None,
 83 |                     })
 84 |                     .map_err(|_| de::Error::invalid_value(Unexpected::Signed(v), &self))
 85 |             }
 86 | 
 87 |             fn visit_map<A>(self, map: A) -> Result<Self::Value, A::Error>
 88 |             where
 89 |                 A: MapAccess<'de>,
 90 |             {
 91 |                 let FrameDtoMap { index, duration } =
 92 |                     FrameDtoMap::deserialize(MapAccessDeserializer::new(map))?;
 93 |                 Ok(FrameDto { index, duration })
 94 |             }
 95 |         }
 96 |         deserializer.deserialize_any(Visitor)
 97 |     }
 98 | }
 99 | 
100 | impl From<Frame> for FrameDto {
101 |     fn from(frame: Frame) -> Self {
102 |         Self {
103 |             duration: Some(frame.duration.as_millis().try_into().unwrap()),
104 |             index: frame.index,
105 |         }
106 |     }
107 | }
108 | 
109 | impl From<Animation> for AnimationDto {
110 |     fn from(animation: Animation) -> Self {
111 |         Self {
112 |             frame_duration: None,
113 |             fps: None,
114 |             total_duration: None,
115 |             mode: match animation.mode {
116 |                 Mode::Once => ModeDto::Once,
117 |                 Mode::RepeatFrom(0) => ModeDto::Repeat,
118 |                 Mode::RepeatFrom(i) => ModeDto::RepeatFrom(i),
119 |                 Mode::PingPong => ModeDto::PingPong,
120 |             },
121 |             frames: animation.frames.into_iter().map(FrameDto::from).collect(),
122 |         }
123 |     }
124 | }
125 | 
126 | impl AnimationDto {
127 |     #[allow(clippy::cast_precision_loss)]
128 |     fn default_duration(&self) -> Result<Option<Duration>, InvalidAnimation> {
129 |         match (
130 |             self.frame_duration.map(Duration::from_millis),
131 |             self.total_duration
132 |                 .map(Duration::from_millis)
133 |                 .map(|d| d.div_f64(self.frames.len() as f64)),
134 |             self.fps
135 |                 .map(|fps| Duration::from_secs(1).div_f64(fps as f64)),
136 |         ) {
137 |             (duration, None, None) | (None, duration, None) | (None, None, duration) => {
138 |                 Ok(duration)
139 |             }
140 |             _ => Err(InvalidAnimation::IncompatibleFrameRate),
141 |         }
142 |     }
143 | }
144 | 
145 | impl TryFrom<AnimationDto> for Animation {
146 |     type Error = InvalidAnimation;
147 | 
148 |     fn try_from(animation: AnimationDto) -> Result<Self, Self::Error> {
149 |         let default_duration = animation.default_duration()?;
150 |         let frames: Vec<Frame> = animation
151 |             .frames
152 |             .into_iter()
153 |             .map(|FrameDto { index, duration }| {
154 |                 let duration = duration
155 |                     .map(Duration::from_millis)
156 |                     .or(default_duration)
157 |                     .filter(|d| !d.is_zero());
158 |                 match duration {
159 |                     Some(duration) => Ok(Frame::new(index, duration)),
160 |                     None => Err(InvalidAnimation::ZeroDuration),
161 |                 }
162 |             })
163 |             .collect::<Result<_, _>>()?;
164 | 
165 |         Ok(Self {
166 |             frames,
167 |             mode: match animation.mode {
168 |                 ModeDto::Repeat => Mode::RepeatFrom(0),
169 |                 ModeDto::RepeatFrom(f) => Mode::RepeatFrom(f),
170 |                 ModeDto::Once => Mode::Once,
171 |                 ModeDto::PingPong => Mode::PingPong,
172 |             },
173 |         })
174 |     }
175 | }
176 | 
177 | #[derive(Debug)]
178 | pub(super) enum InvalidAnimation {
179 |     ZeroDuration,
180 |     IncompatibleFrameRate,
181 | }
182 | 
183 | impl Display for InvalidAnimation {
184 |     fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
185 |         match self {
186 |             InvalidAnimation::ZeroDuration => write!(f, "invalid duration, must be > 0"),
187 |             InvalidAnimation::IncompatibleFrameRate => {
188 |                 write!(f, "fps is incompatible with frame_duration")
189 |             }
190 |         }
191 |     }
192 | }
193 | 
194 | impl Error for InvalidAnimation {}
195 | 
196 | #[cfg(test)]
197 | mod tests {
198 |     use super::*;
199 | 
200 |     use crate::{animation::Mode, Frame, FrameRate};
201 |     use std::time::Duration;
202 | 
203 |     #[rstest]
204 |     fn deserialize_serialize(
205 |         #[values(
206 |             Animation::from_indices(0..=2, FrameRate::from_fps(2.0)),
207 |             Animation::from_indices(0..=2, FrameRate::from_fps(2.0)).once(),
208 |             Animation::from_indices(0..=2, FrameRate::from_fps(2.0)).repeat(),
209 |             Animation::from_indices(0..=2, FrameRate::from_fps(2.0)).repeat_from(1),
210 |             Animation::from_indices(0..=2, FrameRate::from_fps(2.0)).ping_pong(),
211 |         )]
212 |         animation: Animation,
213 |     ) {
214 |         let yaml: String = serde_yaml::to_string(&animation).unwrap();
215 |         let from_yaml: Animation = serde_yaml::from_str(&yaml).unwrap();
216 |         assert_eq!(animation, from_yaml);
217 |         let toml: String = toml::to_string(&animation).unwrap();
218 |         let from_toml: Animation = toml::from_str(&toml).unwrap();
219 |         assert_eq!(animation, from_toml);
220 |     }
221 | 
222 |     #[test]
223 |     fn parse() {
224 |         // given
225 |         let content = "
226 |             mode: PingPong
227 |             frames:
228 |               - index: 0 # index in the sprite sheet for that frame
229 |                 duration: 100 # duration of the frame in milliseconds
230 |               - index: 1
231 |                 duration: 100
232 |               - index: 2
233 |                 duration: 120";
234 | 
235 |         // when
236 |         let animation: Animation = serde_yaml::from_str(content).unwrap();
237 | 
238 |         // then
239 |         assert_eq!(animation.mode, Mode::PingPong);
240 |         assert_eq!(
241 |             animation.frames,
242 |             vec![
243 |                 Frame::new(0, Duration::from_millis(100)),
244 |                 Frame::new(1, Duration::from_millis(100)),
245 |                 Frame::new(2, Duration::from_millis(120)),
246 |             ]
247 |         );
248 |     }
249 | 
250 |     #[test]
251 |     fn default_mode() {
252 |         // given
253 |         let content = "
254 |             frames:
255 |               - index: 0
256 |                 duration: 100";
257 | 
258 |         // when
259 |         let animation: Animation = serde_yaml::from_str(content).unwrap();
260 | 
261 |         // then
262 |         assert_eq!(animation.mode, Mode::RepeatFrom(0));
263 |     }
264 | 
265 |     #[test]
266 |     fn repeat() {
267 |         // given
268 |         let content = "
269 |             mode: Repeat
270 |             frames:
271 |               - index: 0
272 |                 duration: 100";
273 | 
274 |         // when
275 |         let animation: Animation = serde_yaml::from_str(content).unwrap();
276 | 
277 |         // then
278 |         assert_eq!(animation.mode, Mode::RepeatFrom(0));
279 |     }
280 | 
281 |     #[test]
282 |     fn once() {
283 |         // given
284 |         let content = "
285 |             mode: Once
286 |             frames:
287 |               - index: 0
288 |                 duration: 100";
289 | 
290 |         // when
291 |         let animation: Animation = serde_yaml::from_str(content).unwrap();
292 | 
293 |         // then
294 |         assert_eq!(animation.mode, Mode::Once);
295 |     }
296 | 
297 |     #[test]
298 |     fn repeat_from() {
299 |         // given
300 |         let content = "
301 |             mode: !RepeatFrom 1
302 |             frames:
303 |               - index: 0
304 |                 duration: 100
305 |               - index: 1
306 |                 duration: 100";
307 | 
308 |         // when
309 |         let animation: Animation = serde_yaml::from_str(content).unwrap();
310 | 
311 |         // then
312 |         assert_eq!(animation.mode, Mode::RepeatFrom(1));
313 |     }
314 | 
315 |     #[test]
316 |     fn zero_duration() {
317 |         // given
318 |         let content = "
319 |             frames:
320 |               - index: 0
321 |                 duration: 0";
322 | 
323 |         // when
324 |         let animation: Result<Animation, _> = serde_yaml::from_str(content);
325 | 
326 |         // then
327 |         assert!(animation.is_err());
328 |     }
329 | 
330 |     #[test]
331 |     fn same_duration_for_all_frames() {
332 |         // given
333 |         let content = "
334 |             frame_duration: 100
335 |             frames:
336 |               - index: 0
337 |               - index: 1
338 |               - index: 2
339 |                 duration: 200
340 |         ";
341 | 
342 |         // when
343 |         let animation: Animation = serde_yaml::from_str(content).unwrap();
344 | 
345 |         // then
346 |         assert_eq!(
347 |             animation.frames,
348 |             vec![
349 |                 Frame::new(0, Duration::from_millis(100)),
350 |                 Frame::new(1, Duration::from_millis(100)),
351 |                 Frame::new(2, Duration::from_millis(200)),
352 |             ]
353 |         );
354 |     }
355 | 
356 |     #[test]
357 |     fn fps() {
358 |         // given
359 |         let content = "
360 |             fps: 5
361 |             frames:
362 |               - index: 0
363 |               - index: 1
364 |               - index: 2
365 |         ";
366 | 
367 |         // when
368 |         let animation: Animation = serde_yaml::from_str(content).unwrap();
369 | 
370 |         // then
371 |         assert_eq!(
372 |             animation.frames,
373 |             vec![
374 |                 Frame::new(0, Duration::from_millis(200)),
375 |                 Frame::new(1, Duration::from_millis(200)),
376 |                 Frame::new(2, Duration::from_millis(200)),
377 |             ]
378 |         );
379 |     }
380 | 
381 |     #[test]
382 |     fn fps_and_global_duration_is_error() {
383 |         let content = "
384 |             fps: 5
385 |             frame_duration: 100
386 |             frames:
387 |               - index: 0
388 |               - index: 1
389 |               - index: 2
390 |         ";
391 |         assert!(serde_yaml::from_str::<Animation>(content).is_err());
392 |     }
393 | 
394 |     #[test]
395 |     fn fps_with_single_frame_duration() {
396 |         let content = "
397 |             fps: 5
398 |             frames:
399 |               - index: 0
400 |               - index: 1
401 |               - index: 2
402 |                 duration: 100
403 |         ";
404 |         let animation: Animation = serde_yaml::from_str::<Animation>(content).unwrap();
405 |         assert_eq!(
406 |             animation,
407 |             Animation::from_frames([
408 |                 Frame::new(0, Duration::from_millis(200)),
409 |                 Frame::new(1, Duration::from_millis(200)),
410 |                 Frame::new(2, Duration::from_millis(100)),
411 |             ])
412 |         );
413 |     }
414 | 
415 |     #[test]
416 |     fn total_duration() {
417 |         let content = "
418 |             total_duration: 30
419 |             frames:
420 |               - index: 0
421 |               - index: 1
422 |               - index: 2
423 |         ";
424 |         let animation: Animation = serde_yaml::from_str::<Animation>(content).unwrap();
425 |         assert_eq!(
426 |             animation,
427 |             Animation::from_frames([
428 |                 Frame::new(0, Duration::from_millis(10)),
429 |                 Frame::new(1, Duration::from_millis(10)),
430 |                 Frame::new(2, Duration::from_millis(10)),
431 |             ])
432 |         );
433 |     }
434 | 
435 |     #[test]
436 |     fn same_duration_for_all_frames_short_hand_yaml() {
437 |         // given
438 |         let content = "
439 |             frame_duration: 100
440 |             frames: [0, 1, 2]
441 |         ";
442 | 
443 |         // when
444 |         let animation: Animation = serde_yaml::from_str(content).unwrap();
445 | 
446 |         // then
447 |         assert_eq!(
448 |             animation.frames,
449 |             vec![
450 |                 Frame::new(0, Duration::from_millis(100)),
451 |                 Frame::new(1, Duration::from_millis(100)),
452 |                 Frame::new(2, Duration::from_millis(100)),
453 |             ]
454 |         );
455 |     }
456 | 
457 |     #[test]
458 |     fn same_duration_for_all_frames_short_hand_toml() {
459 |         // given
460 |         let content = "
461 |             frame_duration = 100
462 |             frames = [0, 1, 2]
463 |         ";
464 | 
465 |         // when
466 |         let animation: Animation = toml::from_str(content).unwrap();
467 | 
468 |         // then
469 |         assert_eq!(
470 |             animation.frames,
471 |             vec![
472 |                 Frame::new(0, Duration::from_millis(100)),
473 |                 Frame::new(1, Duration::from_millis(100)),
474 |                 Frame::new(2, Duration::from_millis(100)),
475 |             ]
476 |         );
477 |     }
478 | }
479 | 


--------------------------------------------------------------------------------
/src/state.rs:
--------------------------------------------------------------------------------
  1 | use std::time::Duration;
  2 | 
  3 | use crate::{animation::Mode, Animation, Frame};
  4 | 
  5 | /// Animation state
  6 | #[derive(Default, Clone)]
  7 | pub struct State {
  8 |     animation_frame_index: usize,
  9 |     sprite_frame_index: usize,
 10 |     elapsed_in_frame: Duration,
 11 |     /// Control ping_pong backward frame navigation.
 12 |     going_backward: bool,
 13 |     is_ended: bool,
 14 | }
 15 | 
 16 | impl State {
 17 |     /// Create a new state
 18 |     #[must_use]
 19 |     pub fn new() -> Self {
 20 |         Self::default()
 21 |     }
 22 | 
 23 |     /// Reset animation state
 24 |     ///
 25 |     /// The animation will restart from the first frame, like if the animation was freshly spawned.
 26 |     pub fn reset(&mut self) {
 27 |         *self = Self::default();
 28 |     }
 29 | 
 30 |     /// Returns the current frame index
 31 |     #[must_use]
 32 |     pub fn frame_index(&self) -> usize {
 33 |         self.sprite_frame_index
 34 |     }
 35 | 
 36 |     /// Returns true if the animation has ended
 37 |     #[must_use]
 38 |     pub fn is_ended(&self) -> bool {
 39 |         self.is_ended
 40 |     }
 41 | 
 42 |     #[must_use]
 43 |     fn frame<'a>(&self, animation: &'a Animation) -> &'a Frame {
 44 |         &animation.frames[self.animation_frame_index % animation.frames.len()]
 45 |     }
 46 | 
 47 |     /// Update the animation state
 48 |     #[allow(dead_code)]
 49 |     pub fn update(&mut self, animation: &Animation, delta: Duration) {
 50 |         debug_assert!(animation.has_frames());
 51 |         let mut frame = self.frame(animation);
 52 |         self.sprite_frame_index = frame.index;
 53 |         self.elapsed_in_frame += delta;
 54 |         while self.elapsed_in_frame >= frame.duration {
 55 |             let on_last_frame = self.animation_frame_index >= animation.frames.len() - 1;
 56 |             match animation.mode {
 57 |                 Mode::RepeatFrom(loop_from) => {
 58 |                     if on_last_frame {
 59 |                         self.animation_frame_index = loop_from;
 60 |                     } else {
 61 |                         self.animation_frame_index += 1;
 62 |                     }
 63 |                 }
 64 |                 Mode::PingPong => {
 65 |                     if self.going_backward {
 66 |                         if self.animation_frame_index == 0 {
 67 |                             self.going_backward = false;
 68 |                             self.animation_frame_index += 1;
 69 |                         } else {
 70 |                             self.animation_frame_index -= 1;
 71 |                         }
 72 |                     } else if on_last_frame {
 73 |                         self.going_backward = true;
 74 |                         self.animation_frame_index -= 1;
 75 |                     } else {
 76 |                         self.animation_frame_index += 1;
 77 |                     }
 78 |                 }
 79 |                 Mode::Once => {
 80 |                     if on_last_frame {
 81 |                         self.is_ended = true;
 82 |                     } else {
 83 |                         self.animation_frame_index += 1;
 84 |                     }
 85 |                 }
 86 |             }
 87 | 
 88 |             self.elapsed_in_frame -= frame.duration;
 89 |             frame = self.frame(animation);
 90 |             self.sprite_frame_index = frame.index;
 91 |         }
 92 |     }
 93 | }
 94 | 
 95 | #[cfg(test)]
 96 | mod tests {
 97 |     use super::*;
 98 |     use crate::FrameRate;
 99 | 
100 |     #[fixture]
101 |     fn frame_duration() -> Duration {
102 |         Duration::from_secs(1)
103 |     }
104 | 
105 |     #[fixture]
106 |     fn frame_rate(frame_duration: Duration) -> FrameRate {
107 |         FrameRate::from_frame_duration(frame_duration)
108 |     }
109 | 
110 |     #[fixture]
111 |     fn smaller_duration(frame_duration: Duration) -> Duration {
112 |         frame_duration - Duration::from_millis(1)
113 |     }
114 | 
115 |     #[rstest]
116 |     fn sprite_index(frame_rate: FrameRate) {
117 |         let animation = Animation::from_indices(3..=5, frame_rate);
118 |         let mut state = State::default();
119 |         state.update(&animation, Duration::ZERO);
120 |         assert_eq!(state.frame_index(), 3);
121 |     }
122 | 
123 |     mod reset {
124 |         use super::*;
125 | 
126 |         #[fixture]
127 |         fn state() -> State {
128 |             State {
129 |                 animation_frame_index: 1,
130 |                 elapsed_in_frame: Duration::from_secs(1),
131 |                 ..Default::default()
132 |             }
133 |         }
134 | 
135 |         #[rstest]
136 |         fn resets_current_frame(mut state: State) {
137 |             state.reset();
138 |             assert_eq!(state.animation_frame_index, 0);
139 |         }
140 | 
141 |         #[rstest]
142 |         fn resets_elapsed_time(mut state: State) {
143 |             state.reset();
144 |             assert_eq!(state.elapsed_in_frame, Duration::ZERO);
145 |         }
146 |     }
147 | 
148 |     mod on_first_frame {
149 |         use super::*;
150 | 
151 |         #[fixture]
152 |         fn animation(frame_rate: FrameRate) -> Animation {
153 |             Animation::from_indices(0..=2, frame_rate)
154 |         }
155 | 
156 |         #[fixture]
157 |         fn state() -> State {
158 |             State::default()
159 |         }
160 | 
161 |         #[rstest]
162 |         fn nothing_happens_if_not_enough_time_has_elapsed_and_index_is_already_set(
163 |             mut state: State,
164 |             animation: Animation,
165 |             smaller_duration: Duration,
166 |         ) {
167 |             state.update(&animation, smaller_duration);
168 |             assert_eq!(state.frame_index(), 0);
169 |         }
170 | 
171 |         #[rstest]
172 |         fn updates_index_if_less_than_expected_index(
173 |             mut state: State,
174 |             frame_rate: FrameRate,
175 |             smaller_duration: Duration,
176 |         ) {
177 |             let animation = Animation::from_indices(1..=3, frame_rate);
178 |             state.update(&animation, smaller_duration);
179 |             assert_eq!(state.frame_index(), 1);
180 |         }
181 | 
182 |         #[rstest]
183 |         fn updates_index_if_greater_than_expected_index(
184 |             mut state: State,
185 |             frame_rate: FrameRate,
186 |             smaller_duration: Duration,
187 |         ) {
188 |             let animation = Animation::from_indices(1..=3, frame_rate);
189 |             state.update(&animation, smaller_duration);
190 |             assert_eq!(state.frame_index(), 1);
191 |         }
192 | 
193 |         #[rstest]
194 |         fn updates_index_if_enough_time_has_elapsed(
195 |             mut state: State,
196 |             animation: Animation,
197 |             frame_duration: Duration,
198 |         ) {
199 |             state.update(&animation, frame_duration);
200 |             assert_eq!(state.frame_index(), 1);
201 |         }
202 | 
203 |         #[rstest]
204 |         fn updates_index_if_enough_time_has_elapsed_after_multiple_updates(
205 |             mut state: State,
206 |             animation: Animation,
207 |             smaller_duration: Duration,
208 |         ) {
209 |             state.update(&animation, smaller_duration);
210 |             state.update(&animation, smaller_duration);
211 |             assert_eq!(state.frame_index(), 1);
212 |         }
213 | 
214 |         #[rstest]
215 |         fn elapsed_duration_is_reset(
216 |             mut state: State,
217 |             animation: Animation,
218 |             frame_duration: Duration,
219 |             smaller_duration: Duration,
220 |         ) {
221 |             state.update(&animation, smaller_duration);
222 |             state.update(&animation, smaller_duration);
223 |             assert_eq!(
224 |                 state.elapsed_in_frame,
225 |                 (smaller_duration + smaller_duration) - frame_duration
226 |             );
227 |         }
228 | 
229 |         #[rstest]
230 |         fn is_not_ended(mut state: State, animation: Animation, frame_duration: Duration) {
231 |             state.update(&animation, frame_duration);
232 |             assert!(!state.is_ended());
233 |         }
234 | 
235 |         #[rstest]
236 |         fn skips_frame_if_too_much_time_elapsed(
237 |             mut state: State,
238 |             animation: Animation,
239 |             frame_duration: Duration,
240 |         ) {
241 |             state.update(&animation, frame_duration * 2);
242 |             assert_eq!(state.frame_index(), 2);
243 |         }
244 |     }
245 | 
246 |     mod repeat_from {
247 |         use crate::Frame;
248 | 
249 |         use super::*;
250 | 
251 |         mod on_last_frame {
252 |             use super::*;
253 | 
254 |             #[fixture]
255 |             fn animation(frame_duration: Duration) -> Animation {
256 |                 Animation::from_frames(vec![
257 |                     Frame::new(0, frame_duration),
258 |                     Frame::new(1, frame_duration),
259 |                     Frame::new(2, frame_duration),
260 |                     Frame::new(3, frame_duration),
261 |                     Frame::new(4, frame_duration),
262 |                 ])
263 |                 .repeat_from(2)
264 |             }
265 | 
266 |             #[fixture]
267 |             fn state() -> State {
268 |                 State {
269 |                     animation_frame_index: 4,
270 |                     elapsed_in_frame: Duration::from_nanos(0),
271 |                     ..Default::default()
272 |                 }
273 |             }
274 | 
275 |             #[rstest]
276 |             fn returns_to_loop_frame(
277 |                 mut state: State,
278 |                 animation: Animation,
279 |                 frame_duration: Duration,
280 |             ) {
281 |                 state.update(&animation, frame_duration);
282 |                 assert_eq!(state.frame_index(), 2);
283 |             }
284 | 
285 |             #[rstest]
286 |             fn is_not_ended(mut state: State, animation: Animation, frame_duration: Duration) {
287 |                 state.update(&animation, frame_duration);
288 |                 assert!(!state.is_ended());
289 |             }
290 |         }
291 | 
292 |         mod after_last_frame {
293 |             use super::*;
294 | 
295 |             #[fixture]
296 |             fn animation(frame_duration: Duration) -> Animation {
297 |                 Animation::from_frames(vec![
298 |                     Frame::new(0, frame_duration),
299 |                     Frame::new(1, frame_duration),
300 |                     Frame::new(2, frame_duration),
301 |                     Frame::new(3, frame_duration),
302 |                 ])
303 |                 .repeat_from(2)
304 |             }
305 | 
306 |             #[fixture]
307 |             fn state() -> State {
308 |                 State {
309 |                     animation_frame_index: 4,
310 |                     elapsed_in_frame: Duration::from_nanos(0),
311 |                     ..Default::default()
312 |                 }
313 |             }
314 | 
315 |             #[rstest]
316 |             fn returns_to_first_frame(
317 |                 mut state: State,
318 |                 animation: Animation,
319 |                 frame_duration: Duration,
320 |             ) {
321 |                 state.update(&animation, frame_duration);
322 |                 assert_eq!(state.frame_index(), 2);
323 |             }
324 | 
325 |             #[rstest]
326 |             fn is_not_ended(mut state: State, animation: Animation, frame_duration: Duration) {
327 |                 state.update(&animation, frame_duration);
328 |                 assert!(!state.is_ended());
329 |             }
330 |         }
331 |     }
332 | 
333 |     mod ping_pong {
334 |         use super::*;
335 | 
336 |         mod on_last_frame {
337 |             use super::*;
338 | 
339 |             #[fixture]
340 |             fn animation(frame_rate: FrameRate) -> Animation {
341 |                 Animation::from_indices(0..=1, frame_rate).ping_pong()
342 |             }
343 | 
344 |             #[fixture]
345 |             fn state() -> State {
346 |                 State {
347 |                     animation_frame_index: 1,
348 |                     elapsed_in_frame: Duration::from_nanos(500),
349 |                     ..Default::default()
350 |                 }
351 |             }
352 | 
353 |             #[rstest]
354 |             fn returns_to_previous_frame(
355 |                 mut state: State,
356 |                 animation: Animation,
357 |                 frame_duration: Duration,
358 |             ) {
359 |                 state.update(&animation, frame_duration);
360 |                 assert_eq!(state.frame_index(), 0);
361 |             }
362 | 
363 |             #[rstest]
364 |             fn changes_state_to_backward(
365 |                 mut state: State,
366 |                 animation: Animation,
367 |                 frame_duration: Duration,
368 |             ) {
369 |                 state.update(&animation, frame_duration);
370 |                 assert!(state.going_backward);
371 |             }
372 |         }
373 | 
374 |         mod going_backward {
375 |             use super::*;
376 | 
377 |             #[fixture]
378 |             fn animation(frame_rate: FrameRate) -> Animation {
379 |                 Animation::from_indices(0..=2, frame_rate).ping_pong()
380 |             }
381 | 
382 |             #[fixture]
383 |             fn state() -> State {
384 |                 State {
385 |                     animation_frame_index: 1,
386 |                     elapsed_in_frame: Duration::from_nanos(500),
387 |                     going_backward: true,
388 |                     ..Default::default()
389 |                 }
390 |             }
391 | 
392 |             #[rstest]
393 |             fn continues_to_previous_frame(
394 |                 mut state: State,
395 |                 animation: Animation,
396 |                 frame_duration: Duration,
397 |             ) {
398 |                 state.update(&animation, frame_duration);
399 |                 assert_eq!(state.frame_index(), 0);
400 |             }
401 |         }
402 |     }
403 | 
404 |     mod run_once {
405 |         use super::*;
406 | 
407 |         #[fixture]
408 |         fn animation(frame_rate: FrameRate) -> Animation {
409 |             Animation::from_indices(0..=1, frame_rate).once()
410 |         }
411 | 
412 |         mod on_first_frame {
413 |             use super::*;
414 | 
415 |             #[fixture]
416 |             fn state() -> State {
417 |                 State {
418 |                     animation_frame_index: 0,
419 |                     elapsed_in_frame: Duration::from_nanos(500),
420 |                     ..Default::default()
421 |                 }
422 |             }
423 | 
424 |             #[rstest]
425 |             fn final_index_set_if_frames_skipped_past_end(
426 |                 mut state: State,
427 |                 animation: Animation,
428 |                 frame_duration: Duration,
429 |             ) {
430 |                 state.update(&animation, frame_duration * 4);
431 |                 assert_eq!(state.frame_index(), 1);
432 |             }
433 |         }
434 | 
435 |         mod on_last_frame {
436 |             use super::*;
437 | 
438 |             #[fixture]
439 |             fn state() -> State {
440 |                 State {
441 |                     animation_frame_index: 1,
442 |                     elapsed_in_frame: Duration::from_nanos(500),
443 |                     ..Default::default()
444 |                 }
445 |             }
446 | 
447 |             #[rstest]
448 |             fn does_nothing(mut state: State, animation: Animation, frame_duration: Duration) {
449 |                 state.update(&animation, frame_duration);
450 |                 assert_eq!(state.frame_index(), 1);
451 |             }
452 | 
453 |             #[rstest]
454 |             fn is_ended(mut state: State, animation: Animation, frame_duration: Duration) {
455 |                 state.update(&animation, frame_duration);
456 |                 assert!(state.is_ended());
457 |             }
458 |         }
459 |     }
460 | }
461 | 


--------------------------------------------------------------------------------