dusk/.claude/animation.md

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:

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)

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:

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.