H073.HxAnimation 0.1.0

HxAnimation — Framework-Agnostic Animation Library for .NET

HxAnimation is a lightweight, high-performance animation library for C# with zero external dependencies. It provides tweening, easing, spring physics, sprite animation, timeline sequencing, and keyframe animation — all using pure System.Numerics types.

Note: This README was generated with the help of AI. The library code itself was written entirely by hand.

Features

• Tweening — Animate any value type with 30+ easing functions
• Spring Physics — Smooth, physically-based motion with convergence detection
• Sprite Animation — Frame-based animation with Once, Loop, and PingPong modes
• Timeline Sequencing — Chain tweens, delays, and callbacks into sequences
• Keyframe Animation — Time-based keyframes with binary search sampling
• Zero Dependencies — Pure C#, no framework required
• AOT Compatible — Works with Native AOT compilation
• Extensible — Implement ITweenValue<T> or ISpringOperations<T> for custom types

Installation

dotnet add package H073.HxAnimation

Or in .csproj:

<PackageReference Include="H073.HxAnimation" Version="0.1.0" />

Quick Start

Tweening

using HxAnimation.Tween;
using HxAnimation.Easing;

// Tween a float from 0 to 100 over 0.5 seconds with ease-out
var tween = Tween<float>.Float(0f, 100f, 0.5f, Ease.OutCubic);

// In your update loop
tween.Update(deltaTime);
float value = tween.Current;

// Vector tweens (System.Numerics)
var move = Tween<Vector2>.Vec2(start, end, 1f, Ease.InOutQuad);
var move3d = Tween<Vector3>.Vec3(start, end, 1f, Ease.OutBack);

Easing

30+ easing functions, all with AggressiveInlining for maximum performance:

using HxAnimation.Easing;

// Use directly as Func<float, float>
var tween = Tween<float>.Float(0f, 1f, 1f, Ease.OutBounce);

// Or look up by enum
Func<float, float> easing = Ease.FromType(EaseType.InOutElastic);

Available: Linear, InQuad/OutQuad/InOutQuad, InCubic/OutCubic/InOutCubic, InQuart/OutQuart/InOutQuart, InQuint/OutQuint/InOutQuint, InSine/OutSine/InOutSine, InExpo/OutExpo/InOutExpo, InCirc/OutCirc/InOutCirc, InBack/OutBack/InOutBack, InElastic/OutElastic/InOutElastic, InBounce/OutBounce/InOutBounce

Spring Physics

using HxAnimation.Spring;

var spring = Spring<float>.Float();
spring.Target = 100f;

// In your update loop
spring.Update(deltaTime);
float value = spring.Current; // smoothly approaches 100

// Configure behavior
var spring = Spring<float>.Float(new SpringSettings
{
    Frequency = 20f,
    MaxSpeed = 5000f,
    ConvergenceThreshold = 0.01f
});

// Snap to value instantly
spring.SnapTo(50f);

Sprite Animation

using HxAnimation.Sprite;

var clip = new SpriteClip(
[
    new SpriteFrame(0, 0.1f),
    new SpriteFrame(1, 0.1f),
    new SpriteFrame(2, 0.1f),
    new SpriteFrame(3, 0.1f),
], PlaybackMode.Loop);

var anim = new SpriteAnimation(clip);

// In your update loop
anim.Update(deltaTime);
int frame = anim.CurrentFrameIndex; // use this to index your spritesheet

Playback modes: Once, Loop, PingPong

Timeline Sequencing

using HxAnimation.Timeline;
using HxAnimation.Easing;

float alpha = 0f;
float scale = 1f;

var timeline = new TimelineBuilder()
    .TweenFloat(0f, 1f, 0.3f, Ease.OutQuad, v => alpha = v)  // fade in
    .Delay(1f)                                                  // wait
    .TweenFloat(1f, 1.2f, 0.1f, Ease.OutBack, v => scale = v) // pop
    .Callback(() => Console.WriteLine("Done!"))                 // fire event
    .TweenFloat(1f, 0f, 0.5f, Ease.InQuad, v => alpha = v)    // fade out
    .Build();

// In your update loop
timeline.Update(deltaTime);

Keyframe Animation

using HxAnimation.Keyframe;
using HxAnimation.Tween;
using HxAnimation.Easing;

// Create a keyframe animation for float values
var anim = new KeyframeAnimation<float>(TweenValueFloat.Instance, Ease.InOutCubic);
anim.Add(0f, 0f);
anim.Add(0.5f, 100f);
anim.Add(1f, 0f);

// Sample at any time
float value = anim.Sample(0.25f);

// Or use the player for multiple tracks
var player = new KeyframePlayer { Loop = true };
player.AddTrack("opacity", anim);
player.Play();

// In your update loop
player.Update(deltaTime);
float opacity = player.GetValue<float>("opacity");

Custom Types

HxAnimation works with any value type. Implement ITweenValue<T> to add support for your own types:

using HxAnimation.Tween;

// Example: support a custom Color struct
public readonly struct Color(float r, float g, float b, float a)
{
    public float R { get; } = r;
    public float G { get; } = g;
    public float B { get; } = b;
    public float A { get; } = a;
}

public sealed class TweenValueColor : ITweenValue<Color>
{
    public static readonly TweenValueColor Instance = new();

    public Color Lerp(Color from, Color to, float t) => new(
        from.R + (to.R - from.R) * t,
        from.G + (to.G - from.G) * t,
        from.B + (to.B - from.B) * t,
        from.A + (to.A - from.A) * t
    );
}

// Now you can tween colors
var fade = new Tween<Color>(
    new Color(1, 1, 1, 1),
    new Color(1, 0, 0, 0),
    0.5f,
    TweenValueColor.Instance,
    Ease.OutQuad
);

For spring support with custom vector types, implement ISpringOperations<T>:

using HxAnimation.Spring;

public sealed class SpringOperationsMyVec : ISpringOperations<MyVector>
{
    public static readonly SpringOperationsMyVec Instance = new();

    public MyVector Add(MyVector a, MyVector b) => new(a.X + b.X, a.Y + b.Y);
    public MyVector Subtract(MyVector a, MyVector b) => new(a.X - b.X, a.Y - b.Y);
    public MyVector Scale(MyVector value, float scalar) => new(value.X * scalar, value.Y * scalar);
    public float MagnitudeSquared(MyVector value) => value.X * value.X + value.Y * value.Y;
    public MyVector Lerp(MyVector from, MyVector to, float t) => Add(from, Scale(Subtract(to, from), t));
    public MyVector Zero => new(0, 0);
}

// Use it
var spring = new Spring<MyVector>(SpringOperationsMyVec.Instance);

Using MonoGame?

Check out AnimationKit — the same API but built directly against MonoGame 3.8.4 types (Microsoft.Xna.Framework.Vector2, Color, Quaternion, etc.).

API Overview

HxAnimation
├── Easing
│   ├── Ease            — 30+ static easing functions
│   └── EaseType        — Enum for all easing types
├── Tween
│   ├── Tween<T>        — Generic tween with Play/Pause/Reset/Complete
│   ├── ITweenValue<T>  — Interface for custom type interpolation
│   └── TweenValueFloat, TweenValueVector2, TweenValueVector3
├── Spring
│   ├── Spring<T>       — Spring physics with convergence detection
│   ├── ISpringOperations<T> — Interface for custom type spring math
│   └── SpringSettings  — Frequency, MaxSpeed, ConvergenceThreshold
├── Sprite
│   ├── SpriteAnimation — Frame-based animation player
│   ├── SpriteClip      — Animation clip definition
│   ├── SpriteFrame     — Frame index + duration
│   └── PlaybackMode    — Once, Loop, PingPong
├── Timeline
│   ├── Timeline        — Sequential step runner
│   └── TimelineBuilder — Fluent builder (TweenFloat, TweenVec2, Delay, Callback)
└── Keyframe
    ├── KeyframeAnimation<T> — Time-based keyframes with binary search
    ├── KeyframePlayer       — Multi-track player with loop support
    └── Keyframe<T>          — Time + Value pair

Contact

Discord: sameplayer