Defines the collection of animations available to a model, linking specific game states or actions (like "idle", "walk", "attack") to animation files (.ska). It also includes parameters controlling animation playback behavior and Inverse Kinematics (IK). 🎬
Purpose: Manages all skeletal animations for a unit or animated object, defining which .ska file plays for which action, and includes settings like default movement speeds and IK constraints.
Where it appears: Included in animated model types: AnimatedUnit, AnimatedObjectNoCollision, AnimatedObjectCollision. See WriteOrder.
Engine impact: Crucial for animation playback. Contains default speeds used by movement logic, IK constraints for targeting/aiming, and links to the actual animation data.
Links a game state/action (identified by file, often conceptually like "Idle" or "Attack") to one or more animation variants (.ska files).
Field
Type
Description
type
int32
Internal type identifier (often 6).
length
int32
Length of the magic string (always 11).
file
string
Always "Battleforge".
unknown
int32
Unknown integer.
unknown2
List[uint8] or int32
Varies based on type. Often a single int32.
vis_job
int16 (If type == 6)
Related to visual state or job type. Export filter in create_animation_set removes keys where vis_job != 0 for non-unit types.
unknown3
int32 (If type == 6)
Unknown integer.
special_mode
int16 (If type <= 5 or 6)
Identifier for a special animation mode or state.
variant_count
int32
Number of animation variants associated with this key.
animation_set_variants
List[AnimationSetVariant]
List of variants, each pointing to a .ska file and defining playback parameters. See AnimationSetVariant. A key must have at least one valid variant to be saved during export.
Animation Set Editor: The primary way to manage AnimationSet data is through the dedicated Animation Set Editor UI panel in the addon. This editor stores the configuration in a JSON blob (ANIM_BLOB_KEY) attached to the main model collection.
JSON Blob: This blob holds lists for mode_keys (linking conceptual names like "Idle" to .ska files and variants) and marker_sets (defining animation events). It also stores top-level parameters like default speeds and IK flags. The blob is the authoritative source during export.
Export (create_animation_set): The exporter reads the JSON blob from the collection. It reconstructs the AnimationSet structure, including ModeAnimationKey, AnimationSetVariant, AnimationMarkerSet, and AnimationMarker objects based on the blob data.
.ska File Links: The AnimationSetVariant.file field is populated from the blob. The exporter ensures it ends with .ska.
IK Constraints: IKAtlas and Constraint data is gathered directly from LIMIT_ROTATION constraints on the Armature's Pose Bones in Blender (collect_ik_atlases_from_blender).
Import (persist_animset_blob_on_collection): The importer reads the AnimationSet from the DRS file, converts it into the JSON blob format (animset_to_blob), and stores this blob on the imported model's collection. The Animation Set Editor UI then reads from this blob. IK constraints are applied to the Armature's Pose Bones (import_animation_ik_atlas).
In-Game Function: The game engine uses AnimationSet to know which .ska animation to play based on the unit's current state (idle, walking, attacking, etc.). It uses the default speeds for movement calculations, applies IK constraints for aiming or foot placement, and triggers events based on AnimationMarker data.
Blob is King: Edits made directly to Blender Actions or Armature constraints (other than IK limits) might not be reflected on export unless the Animation Set Editor blob is updated accordingly. The blob stored on the collection is the primary source of truth for export.
Animated Object Filter: For AnimatedObjectCollision / AnimatedObjectNoCollision types, the exporter filters out ModeAnimationKey entries where vis_job is not 0.