Internal Animation Format

== Tools ==
If you're coming here to find out about how to take advantage of Second Life's internal animation format (.anim), you may find the below tools of use.
 .anim file format utilities
Name 	Notes
Anim-converter	Converts .bvh files into Second Life .anim files.
Anim2BVH 	Inverse of the above, converts .anim files into .bvh files.
Anim Hacker 	Tool for manipulating .anim files. Can be used to edit joint priorities, add constraints, and more!
tanimbomb 	Python CLI tool for making simple bulk-edits to multiple anim files at once, especially joint removal and animation mirroring
AnimMaker 	Older tool, equivalent to AnimHacker. (Source Code available in archive)
==Overview==
From a programming perspective, there are several steps to uploading an animation from a BVH (BioVision Hierarchy) file:
# Read and parse the BVH file, creating an LLKeyframeMotion object containing the motion data.
# Gather input from the user (via the upload preview floater) for things like animation priority, facial expression, and looping; these settings are stored in the LLKeyframeMotion object.
# Serialize the LLKeyframeMotion object as LLSD.
# Upload the serialized data to the asset server.
Before other viewers can play an animation, they must:
# Download the serialized data from the asset server.
# Deserialize it to an LLKeyframeMotion object.
Relevant source files:
* llbvhloader.cpp
* llkeyframemotion.cpp:deserialize()
Note: the binary file is little endian.
==Header==
The first part of the animation data is a header describing various details about the animation as a whole. The elements, in order, are:
==Joint Data==
After the header is data for each joint in the skeleton:
Note: Unused bones need not be included in the file.
===Joint Rotation Keys===
At the start of the rotation data for each bone is the total number of rotation keys:
If the bone has no rotation based keyframes, this value must be 0.
Then, for each rotation key:
Note: These three values X Y Z appear to be the first three values of a truncated quaternion with the W term being calculated afterwards. 
Since a quaternion is X2 + Y2 + Z2 + W2 = 1 as long as you assume the W term has a consistent sign the X Y Z terms will be accurate.
===Joint Position Keys===
At the start of the position data is the total number of position keys:
If the bone has no position based animations, this value must be 0.
Then, for each position key, position data is measured from Avatar Center ( mPelvis ), not joint resting position
( IE [0,0,0] is not joint resting position, it'll be the bone's position in parent coordinate space)
with the exception of the mPelvis bone which is stored in world space coordinates.:
==Constraints==
After the joint data are a number of entries for joint constraints. Constraints can target an avatar's parts in relation to each other or the ground (IK).
Then, for each joint constraint:
* The implementation of constraint type Point is incomplete, and is considered non-functional. Until further notice, all constraints should use the Plane type.
:The above does not seem to be true, both types would seem to be working. (Jenna Huntsman tested )
=== Jenna's notes on constraints ===
* chain_length is not inclusive of the source bone itself, so for example, if the source bone is R_HAND, setting a chain_length of 2 will use R_LOWER_ARM (elbow joint) and R_UPPER_ARM (shoulder joint).
** Setting a chain_length of more than 4 will prevent the animation from playing - the animation will upload, but will not play.
** Setting a chain_length of 4 (both constraint types) will cause the viewer to crash.
* target_offset uses an axis layout of X+ forward, Y+ left, Z+ up.
** Constraints only seem to work reliably if target_offset has a value of 1 on the Z axis. The values on the X and Y axis can be anything however.
* source_offset uses an axis layout of X+ forward, Y+ left, Z+ up.
** The distance units expected are of an unknown unit, however it does not seem to be meters or inches. (Also true of target_offset)
** llkeyframemotion.cpp would seem to suggest that constraints are inherited from a BVH upon conversion to .anim, which would make the units be inches (as is standard for BVH animations in SL); however in-world testing casts doubt upon this.
* target_dir is unused, however is likely a unit vector relative to the armature root.
** As such, bone rotations can be manipulated by rot keys as normal, however the rotation will not be relative to the target volume.
** It seems that while target_dir is present in the file format for constraints, it was never implemented (As per llkeyframemotion.cpp).
* While GROUND is a recognized and implemented target volume, server-side checks prevent uploads of animations making use of this constraint target.
* There seems to be a hard limit of 10 constraints per animation (as per llkeyframemotion.cpp).
* Constraints always follow the shortest path from their source to their destination, irrespective of 'legal' joint rotations. (Meaning to say, constraints can cause bones to move in an odd way (e.g. an arm clipping inside your body) if that is the shortest path.)
* Unlike regular animations, Constraints seem to require an intact armature from the skeleton root (mPelvis) to the source and target bones; Otherwise the animation will not play.
** The bones do not need to be animated, they only need to be present in the .anim file.
* Constraints do respect animation priority (The global animation priority, as defined by base_priority, not the per joint priority), meaning it's possible to stack constraints, but not within the same animation.