sequence.hpp

Go to the documentation of this file.

#pragma once

 
#include <cstdint>
#include <utility>
 
#include <welder/vocabulary.hpp>
 
#include <wowlib/core/lang.hpp>
#include <wowlib/core/client_version.hpp>
#include <wowlib/formats/common/flags.hpp>
#include <wowlib/formats/m2/boundaries.hpp>
#include <wowlib/formats/m2/root/record/track.hpp>
 
namespace wowlib::formats::m2::root::record {
  struct [[
      =welder::weld,
      =welder::weld_as("M2Sequence"),
  WOWLIB_CS_FAMILY_SURFACE
      =welder::doc(R"(
        One animation sequence entry. Abstract over the client version; construct a concrete
        version with M2Sequence.ForVersion / for_version.)")
    ]] M2SequenceBase {
    // The concretes default operator== — the base must be comparable too.
    bool operator==(const M2SequenceBase&) const = default;
  };
 
  enum class [[
      =welder::weld,
      =welder::flags,
      =welder::doc("M2Sequence flags — the 0x20/0x40/0x130 combination decides "
        "where the sequence's track data lives (.m2 vs .anim file).")
    ]] SequenceFlags : std::uint32_t {
    SetsRuntimeBlend [[=welder::doc("Sets 0x80 when loaded (M2Init).")]] = 0x1,
    TiltIn [[=welder::doc("Model tilts over X/Y by the end of the animation.")]] = 0x2,
    TiltOut [[=welder::doc("Model starts tilted and returns upright.")]] = 0x4,
    TiltFixed [[=welder::doc("Model stays tilted for the whole animation.")]] = 0x8,
    LoadedLowPriority [[=
      welder::doc("Set at runtime for loaded low-priority sequences.")]] = 0x10,
    DataInM2 [[=welder::doc("Primary bone sequence: track data is in the .m2 "
      "itself, not an .anim file.")]] = 0x20,
    Alias [[=welder::doc("The sequence is an alias: follow alias_next until an "
      "entry without this flag owns the data.")]] = 0x40,
    Blended [[=welder::doc("Blend (lerp) into/out of this sequence.")]] = 0x80,
    StoredInModel [[=welder::doc("Sequence stored in the model (0x100).")]] = 0x100,
    SplitBlendTimes [[=
      welder::doc("blend_time is the in/out pair, not one u32.")]] = 0x200,
    Legion0x800 [[=welder::doc("Seen in Legion 24500 models.")]] = 0x800
  };

  constexpr bool sequenceDataExternal(std::uint32_t flags) {
    return (flags & 0x130u) == 0;
  }
 
  namespace detail {
    // The annotated era layouts; instantiate through the canonicalizing
    // aliases below, never directly.
    template <ClientVersion V>
    struct M2Sequence;
 
    template <ClientVersion V> requires (V < M2PerSequenceTimelines)
    struct [[
        =welder::weld,
        =welder::doc(
          "An animation sequence, pre-WotLK layout: global start/end timestamps, "
          "one u32 blend time.")
      ]] M2Sequence<V> : M2SequenceBase {
      [[=welder::doc("Animation id in AnimationData.dbc.")]]
      std::uint16_t id = 0;
      [[=welder::doc("Which variation of the animation this is.")]]
      std::uint16_t variationIndex = 0;
      [[=welder::doc("Slice start on the global timeline.")]]
      std::uint32_t startTimestamp = 0;
      [[=welder::doc("Slice end on the global timeline.")]]
      std::uint32_t endTimestamp = 0;
      [[=welder::doc("Character move speed during the sequence.")]]
      float movespeed = 0;
      [[=welder::doc("See SequenceFlags.")]]
      SequenceFlags flags{};
      [[=welder::doc("Playback probability weight (sums to 0x7FFF per id).")]]
      std::int16_t frequency = 0;
      [[=welder::doc("Unused alignment padding.")]]
      std::uint16_t padding = 0;
      [[=welder::doc("Random repetition bounds; both 0 = no repeat.")]]
      M2Range replay{};
      [[=welder::doc("Transition blend duration, milliseconds.")]]
      std::uint32_t blendTime = 0;
      [[=welder::doc("Bounds while the sequence plays.")]]
      M2Bounds bounds{};
      [[=welder::doc("Next variation index, -1 if none.")]]
      std::int16_t variationNext = -1;
      [[=welder::doc("Alias target (flags & 0x40 chains).")]]
      std::uint16_t aliasNext = 0;
 
      [[=welder::doc("Whether this sequence is an alias (flag 0x40): it owns "
        "NO track data — resolve it by following alias_next. "
        "Files still carry stale array records for aliases "
        "(dead offsets, junk values), so they are never "
        "chased.")]]
      constexpr bool isAlias() const {
        return (std::to_underlying(flags) & 0x40u) != 0;
      }
 
      [[=welder::doc("Whether this sequence owns an external .anim file: its "
        "data is low-priority (0x10/0x20/0x100 all clear) and "
        "it is no alias.")]]
      constexpr bool ownsAnimFile() const {
        return sequenceDataExternal(std::to_underlying(flags)) && !isAlias();
      }
 
      bool operator==(const M2Sequence&) const = default;
    };
 
    template <ClientVersion V> requires (V >= M2PerSequenceTimelines && V < M2SplitBlendTimes)
    struct [[
        =welder::weld,
        =welder::doc(
          "An animation sequence, WotLK through MoP layout: an own duration, one "
          "u32 blend time.")
      ]] M2Sequence<V> : M2SequenceBase {
      [[=welder::doc("Animation id in AnimationData.dbc.")]]
      std::uint16_t id = 0;
      [[=welder::doc("Which variation of the animation this is.")]]
      std::uint16_t variationIndex = 0;
      [[=welder::doc("Sequence length, milliseconds.")]]
      std::uint32_t duration = 0;
      [[=welder::doc("Character move speed during the sequence.")]]
      float movespeed = 0;
      [[=welder::doc("See SequenceFlags.")]]
      SequenceFlags flags{};
      [[=welder::doc("Playback probability weight (sums to 0x7FFF per id).")]]
      std::int16_t frequency = 0;
      [[=welder::doc("Unused alignment padding.")]]
      std::uint16_t padding = 0;
      [[=welder::doc("Random repetition bounds; both 0 = no repeat.")]]
      M2Range replay{};
      [[=welder::doc("Transition blend duration, milliseconds.")]]
      std::uint32_t blendTime = 0;
      [[=welder::doc("Bounds while the sequence plays.")]]
      M2Bounds bounds{};
      [[=welder::doc("Next variation index, -1 if none.")]]
      std::int16_t variationNext = -1;
      [[=welder::doc("Alias target (flags & 0x40 chains).")]]
      std::uint16_t aliasNext = 0;
 
      [[=welder::doc("Whether this sequence is an alias (flag 0x40): it owns "
        "NO track data — resolve it by following alias_next. "
        "Files still carry stale array records for aliases "
        "(dead offsets, junk values), so they are never "
        "chased.")]]
      constexpr bool isAlias() const {
        return (std::to_underlying(flags) & 0x40u) != 0;
      }
 
      [[=welder::doc("Whether this sequence owns an external .anim file: its "
        "data is low-priority (0x10/0x20/0x100 all clear) and "
        "it is no alias.")]]
      constexpr bool ownsAnimFile() const {
        return sequenceDataExternal(std::to_underlying(flags)) && !isAlias();
      }
 
      bool operator==(const M2Sequence&) const = default;
    };
 
    template <ClientVersion V> requires (V >= M2SplitBlendTimes)
    struct [[
        =welder::weld,
        =welder::doc(
          "An animation sequence, WoD+ layout: an own duration, split "
          "blend-in/out times.")
      ]] M2Sequence<V> : M2SequenceBase {
      [[=welder::doc("Animation id in AnimationData.dbc.")]]
      std::uint16_t id = 0;
      [[=welder::doc("Which variation of the animation this is.")]]
      std::uint16_t variationIndex = 0;
      [[=welder::doc("Sequence length, milliseconds.")]]
      std::uint32_t duration = 0;
      [[=welder::doc("Character move speed during the sequence.")]]
      float movespeed = 0;
      [[=welder::doc("See SequenceFlags.")]]
      SequenceFlags flags{};
      [[=welder::doc("Playback probability weight (sums to 0x7FFF per id).")]]
      std::int16_t frequency = 0;
      [[=welder::doc("Unused alignment padding.")]]
      std::uint16_t padding = 0;
      [[=welder::doc("Random repetition bounds; both 0 = no repeat.")]]
      M2Range replay{};
      [[=welder::doc("Blend-in duration, milliseconds.")]]
      std::uint16_t blendTimeIn = 0;
      [[=welder::doc("Blend-out duration, milliseconds.")]]
      std::uint16_t blendTimeOut = 0;
      [[=welder::doc("Bounds while the sequence plays.")]]
      M2Bounds bounds{};
      [[=welder::doc("Next variation index, -1 if none.")]]
      std::int16_t variationNext = -1;
      [[=welder::doc("Alias target (flags & 0x40 chains).")]]
      std::uint16_t aliasNext = 0;
 
      [[=welder::doc("Whether this sequence is an alias (flag 0x40): it owns "
        "NO track data — resolve it by following alias_next. "
        "Files still carry stale array records for aliases "
        "(dead offsets, junk values), so they are never "
        "chased.")]]
      constexpr bool isAlias() const {
        return (std::to_underlying(flags) & 0x40u) != 0;
      }
 
      [[=welder::doc("Whether this sequence owns an external .anim file: its "
        "data is low-priority (0x10/0x20/0x100 all clear) and "
        "it is no alias.")]]
      constexpr bool ownsAnimFile() const {
        return sequenceDataExternal(std::to_underlying(flags)) && !isAlias();
      }
 
      bool operator==(const M2Sequence&) const = default;
    };
  }

  template <ClientVersion V>
  using M2Sequence = detail::M2Sequence<canonicalVersion(V, M2SequencePivots, M2Versions)>;
 
  struct [[
      =welder::weld,
      =welder::doc("A pre-WotLK playable-animation fallback: the substitute "
        "animation id plus how to play it (0 normal, 1 backwards, "
        "2 frame-by-frame, 3 freeze).")
    ]] M2SequenceFallback {
    [[=welder::doc("Substitute animation id in AnimationData.dbc.")]]
    std::int16_t fallbackAnimationId = 0;
    [[=welder::doc("Playback mode: 0 normal, 1 backwards, 2 frame-by-frame, "
      "3 freeze.")]]
    std::int16_t flags = 0;
 
    bool operator==(const M2SequenceFallback&) const = default;
  };
 
  static_assert(sizeof(M2Sequence<versions::Vanilla>) == 68);
  static_assert(sizeof(M2Sequence<versions::Wotlk>) == 64);
  static_assert(sizeof(M2Sequence<versions::Wod>) == 64);
  static_assert(sizeof(M2SequenceFallback) == 4);
}