dusk/src/dusk/entity/component/animation/entityanimation.h

/**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */

#pragma once
#include "entity/entitybase.h"
#include "animation/animation.h"

typedef struct {
  animation_t anim;

  /**
   * Playback rate multiplier; 1.0 = normal speed. This branch's
   * animation_t has no speed field of its own (animationUpdate() just
   * takes a deltaTime), so the multiplier is tracked here and applied to
   * TIME.delta before calling animationUpdate() each tick.
   */
  float_t speed;

  /**
   * True while entityAnimationUpdate() should advance anim's time each
   * tick. This branch's animation_t has no playing field of its own --
   * advancing is purely a function of whether animationUpdate() is
   * called -- so playback gating lives here instead.
   */
  bool_t playing;
} entityanimation_t;

/**
 * Initializes the animation component: no keyframes set, and registers
 * entityAnimationUpdate as an update callback. Call
 * entityAnimationSetKeyframes() before entityAnimationPlay().
 *
 * @param entityId The entity ID.
 * @param componentId The component ID.
 */
void entityAnimationInit(
  const entityid_t entityId,
  const componentid_t componentId
);

/**
 * Gets the underlying animation structure (temporarily) for the given
 * entity. Prefer the dedicated getters/setters where possible.
 *
 * @param entityId The entity ID.
 * @param componentId The component ID.
 * @return The animation component data for the given entity and
 * component ID.
 */
entityanimation_t *entityAnimationGet(
  const entityid_t entityId,
  const componentid_t componentId
);

/**
 * Sets the entity's keyframes, stopped, at speed 1.0, non-looping. See
 * animationInit() -- keyframes/keyframeCounts and the keyframe_t data
 * they point to are not copied, and must outlive this component (e.g.
 * static/const arrays owned by the caller).
 *
 * @param entityId The entity ID.
 * @param componentId The component ID.
 * @param keyframes Flat array of keyframe_t, one contiguous run per layer
 * (layer's run length is keyframeCounts[layer]) -- see animationInit().
 * @param keyframeCounts Array of layerCount keyframe counts, matching the
 * per-layer runs in keyframes.
 * @param layerCount The number of layers/channels.
 */
void entityAnimationSetKeyframes(
  const entityid_t entityId,
  const componentid_t componentId,
  keyframe_t *keyframes,
  uint16_t *keyframeCounts,
  const uint16_t layerCount
);

/**
 * Starts (or restarts) playback from time 0.
 *
 * @param entityId The entity ID.
 * @param componentId The component ID.
 */
void entityAnimationPlay(
  const entityid_t entityId,
  const componentid_t componentId
);

/**
 * Stops playback without resetting the current time.
 *
 * @param entityId The entity ID.
 * @param componentId The component ID.
 */
void entityAnimationStop(
  const entityid_t entityId,
  const componentid_t componentId
);

/**
 * Checks whether the animation is currently playing.
 *
 * @param entityId The entity ID.
 * @param componentId The component ID.
 * @return True if playing.
 */
bool_t entityAnimationIsPlaying(
  const entityid_t entityId,
  const componentid_t componentId
);

/**
 * Sets whether the animation loops on reaching its final keyframe, rather
 * than stopping there.
 *
 * @param entityId The entity ID.
 * @param componentId The component ID.
 * @param loop True to loop, false to stop at the end.
 */
void entityAnimationSetLoop(
  const entityid_t entityId,
  const componentid_t componentId,
  const bool_t loop
);

/**
 * Sets the animation's playback rate multiplier.
 *
 * @param entityId The entity ID.
 * @param componentId The component ID.
 * @param speed The new playback rate; 1.0 = normal speed.
 */
void entityAnimationSetSpeed(
  const entityid_t entityId,
  const componentid_t componentId,
  const float_t speed
);

/**
 * Evaluates one of the animation's channels at its current playback
 * time, regardless of whether it's currently playing.
 *
 * @param entityId The entity ID.
 * @param componentId The component ID.
 * @param channelIndex The channel to evaluate, in [0, channelCount) as
 * passed to entityAnimationSetKeyframes().
 * @return That channel's value at the current time.
 */
float_t entityAnimationGetValue(
  const entityid_t entityId,
  const componentid_t componentId,
  const uint16_t channelIndex
);

/**
 * Per-tick update for the animation component: calls animationUpdate()
 * (a no-op if not playing). Registered automatically as an update
 * callback by entityAnimationInit.
 *
 * @param entityId The entity ID.
 * @param componentId The component ID.
 * @param user Unused.
 */
void entityAnimationUpdate(
  const entityid_t entityId,
  const componentid_t componentId,
  void *user
);