# Animation System

Source: `src/dusk/animation/`

Lightweight keyframe-based value interpolation using fixed-point math throughout.

---

## Easing (`animation/easing.h`)

`easingApply(type, t)` applies an easing function to a normalized time value `t ∈ [0, FIXED_ONE]` and returns the eased value in the same range.

All functions are also callable directly:

```c
fixed_t t = FIXED(0.5f);
fixed_t out = easingApply(EASING_IN_OUT_CUBIC, t);
```

Available easing types (all in `easingtype_t`):

| Enum value | Curve |
|---|---|
| `EASING_LINEAR` | straight line |
| `EASING_IN_SINE` / `OUT` / `IN_OUT` | sinusoidal |
| `EASING_IN_QUAD` / `OUT` / `IN_OUT` | quadratic |
| `EASING_IN_CUBIC` / `OUT` / `IN_OUT` | cubic |
| `EASING_IN_QUART` / `OUT` / `IN_OUT` | quartic |
| `EASING_IN_BACK` / `OUT` / `IN_OUT` | overshoots slightly |

`EASING_FUNCTIONS[EASING_COUNT]` is a table of `easingfn_t` function pointers for when you need to pick an easing at runtime without a switch.

---

## Keyframes (`animation/keyframe.h`)

```c
typedef struct {
  fixed_t time;          // time point this keyframe is at
  fixed_t value;         // output value at this time
  easingtype_t easing;   // easing to apply when interpolating toward the NEXT keyframe
} keyframe_t;
```

Keyframe arrays should be sorted ascending by `time`.

---

## Animation (`animation/animation.h`)

`animation_t` wraps a keyframe array and provides value lookup:

```c
keyframe_t frames[] = {
  { FIXED(0.0f), FIXED(0.0f), EASING_LINEAR },
  { FIXED(1.0f), FIXED(1.0f), EASING_IN_OUT_CUBIC },
  { FIXED(2.0f), FIXED(0.0f), EASING_LINEAR },
};

animation_t anim;
animationInit(&anim, frames, 3);

fixed_t value = animationGetValue(&anim, FIXED(0.75f));   // interpolated
```

`animationGetValue` finds the surrounding keyframes for the given `time`, computes the local `t` within that segment, applies the keyframe's easing, and linearly interpolates between the two keyframe values.

The animation does not own the keyframe array — it holds a pointer. Pass a static or long-lived array.

---

## Usage in the engine

Entity animations (`entityanim_t`) do NOT use this system — they use a simple countdown timer (`animTime`) and a state enum. The `animation_t` system is intended for property animation: UI transitions, camera easing, visual effects, anything that needs a time → value curve.