A simple, generic, and flexible keyframe animation library for Rust.
KramaFrame provides a straightforward way to manage and update multiple animations, map their progress to value ranges, and apply various easing functions for smooth and dynamic transitions.
- Manage multiple animations using string-based class names and numeric IDs.
- A rich set of built-in easing functions:
LinearEaseIn,EaseOut,EaseInOutSteps(n)for stepped animations- Custom
CubicBeziercurves
- Generic over time (
TRES) and progress (PRES) data types for maximum flexibility. - Easily map animation progress (from 0.0 to 1.0) to any numerical output range.
- Play animations forwards or in reverse.
- Update all active animations with a single call in your game or application loop.
Add kramaframe to your project's Cargo.toml:
[dependencies]
kramaframe = "0.2.*"Or, add it via the command line:
cargo add kramaframeHere's a basic example of animating a value from 80 to 100 over a set duration.
use kramaframe::{BTclasslist, BTframelist, KramaFrame, keyframe::KeyFrameFunction};
fn main() {
// 1. Create a new KramaFrame instance.
// The type parameters define the storage for animation classes and instances.
// Here, BTframelist<_, i32> uses a default time representation (f64) and i32 for progress.
let mut kramaframe: KramaFrame<BTclasslist, BTframelist<_, i32>> = KramaFrame::default();
// 2. Define an animation "class" with an easing function.
// We'll call it "animation1" and use Linear easing for a constant speed.
kramaframe.extend_iter_classlist([("animation1", KeyFrameFunction::Linear)]);
// 3. Create a specific instance of the animation.
// We give it a unique ID (1) and a duration (1.0 in abstract units).
kramaframe.insert_new_id("animation1", 1, 1.0);
// 4. Start the animation. This sets its progress to the beginning.
kramaframe.restart_progress("animation1", 1);
// 5. In your application's update loop, advance the animation time.
println!("--- Forward Animation ---");
for _ in 0..=120 {
// Update all animations by a delta time.
// Here, we simulate 120 frames for a total duration of 1.0.
kramaframe.update_progress(1.0 / 120.0);
// 6. Get the current animated value.
// We map the animation's progress (0.0 to 1.0) to a target range (80.0 to 100.0).
let progress = kramaframe.get_progress_f32("animation1", 1).unwrap_or(0.0);
let value = kramaframe.get_value_byrange_inclusive("animation1", 1, 80f32..=100f32);
println!("progress= {:.2}, value = {:.2}", progress, value);
}
// 7. You can also reverse the animation.
kramaframe.reverse_animate("animation1", 1);
println!("\n--- Reverse Animation ---");
for _ in 0..=120 {
kramaframe.update_progress(1.0 / 120.0);
let progress = kramaframe.get_progress_f32("animation1", 1).unwrap_or(0.0);
let value = kramaframe.get_value_byrange_inclusive("animation1", 1, 80f32..=100f32);
println!("progress= {:.2}, value = {:.2}", progress, value);
}
}KramaFrame uses KeyFrameFunction to control the rate of change of an animation, allowing for more natural and interesting motion.
KeyFrameFunction::Linear: Constant speed.KeyFrameFunction::EaseIn: Starts slow, then accelerates.KeyFrameFunction::EaseOut: Starts fast, then decelerates.KeyFrameFunction::EaseInOut: Starts and ends slow, with acceleration in the middle.KeyFrameFunction::Steps(n): Divides the animation intondiscrete, instantaneous steps.KeyFrameFunction::new_cubic_bezier_f32(x1, y1, x2, y2): Defines a custom animation curve using Cubic Bezier control points, similar to CSScubic-bezier().
You can define multiple animation classes, each with its own easing function.
use kramaframe::{KramaFrame, keyframe::KeyFrameFunction, keylist::KeyList};
let mut kramaframe = KramaFrame::default();
// Define different animation classes
kramaframe.extend_iter_classlist([
("linear", KeyFrameFunction::Linear),
("easein", KeyFrameFunction::EaseIn),
("easeinout", KeyFrameFunction::EaseInOut),
("bounce", KeyFrameFunction::new_cubic_bezier_f32(0.0, 1.26, 1.0, -0.79)),
("staircase", KeyFrameFunction::Steps(5)),
]);
// Create instances for each animation class with a duration of 1.0
kramaframe.insert_new_id("linear", 1, 1.0);
kramaframe.insert_new_id("easein", 1, 1.0);
// ... and so on for the other classes
// In your update loop, you can get values for each:
kramaframe.update_progress(1.0 / 60.0); // ~60 FPS
let linear_val = kramaframe.get_value_byrange("linear", 1, 0..100);
let easein_val = kramaframe.get_value_byrange("easein", 1, 0..100);
println!("Linear: {}, EaseIn: {}", linear_val, easein_val);KramaFrame provides convenient macros for initializing animation sets using a concise syntax.
The ukramaframe! macro is designed for no_std environments or scenarios where you want stack-allocated storage (using UClassList and UFrameList). It requires explicit type parameters for Time Resolution (TRES), Progress (PRES), and ID type.
use kramaframe::{keylist::TRES16Bits, ukramaframe};
// Syntax: <TRES, PRES, ID_TYPE> "class" Function [ID1, ID2] Duration Unit;
let mut krama = ukramaframe!(<TRES16Bits, i16, u32>
"linear_anim" Linear [1, 2] 2.0 s;
"ease_anim" EaseIn [3] 1.5 s;
);
// Start an animation
krama.restart_progress("linear_anim", 1);The btkramaframe! macro creates a KramaFrame using BTreeMap for its internal storage. This is the preferred choice for general-purpose applications using std or alloc where the number of animations may vary.
use kramaframe::btkramaframe;
// Uses default BTreeMap storage
let mut krama = btkramaframe!(
<u32, i32>
"move" EaseInOut [10, 20] 0.5 s;
"fade" Linear [1] 1.0 s;
);
// Update and retrieve value
krama.update_progress(0.016); // 16ms delta
let val = krama.get_value_byrange("move", 10, 0..100);You can find more detailed examples in the /examples directory of the repository:
iterrange.rs: A complete, runnable version of the basic usage example.allkeyframe.rs: Demonstrates and visualizes all availableKeyFrameFunctiontypes.reverse.rs: Demonstrates how to reverse the direction of an animation instance.reverserange.rs: Demonstrates how to reverse the range of an animation instance.generic.rs: Demonstrates how to use generic types withKramaFrame.
tuiexample.rs: Demonstrates how to useKramaFramewith a TUI (Text User Interface) library.
2025-11-06.22-44-34.mp4
kramaviz.rs: A higly efficient Visualizer sync with fluid animation. This Visualizer use less CPU and less memory than cava. where cava randomly flicker whereas kramaviz won't.
compressed_no_audio.mp4
This project is licensed under
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
If you are interested in adding a special or useful feature, please feel free to open an Issue or Pull Request!