Animation Format

From CloudModding OoT Wiki
Jump to: navigation, search

Animations in Ocarina of Time and Majora's Mask follow what I find to be a peculiar format. To have a working animation, the given resource file must have both a hierarchy and animation(s) to go with it.

Capable Viewers

ZSaten, OZMAV2 and z64anim are all viewers which can render normal skeletal structures (hierarchies) with their animations. ZSaten is the only viewer for Link and the beta format used in object_human. z64anim is currently the only editor for hierarchies and animations.

Normal Animations

Animations are composed of three chunks: rotation values, rotation index, and a header

Rotation values

Pretty simple. This is just a list of unsigned 16 bit values that are referenced by the rotation index.
Example:

00004000 8000C000

This would be four values, 0/360 degrees, 90 degrees, 180 degrees, and 270 degrees Note: the first value in most lists of rotation values is 0.

Rotation index

A little more complex. It's size is exactly 6 + (6 * Number of limbs). The first three 16 bit values are translation values for the whole model (in xyz order), and the rest of the six byte groups are rotation values for each part of the hierarchy, in the order they are listed in the hierarchy.
Example:

00000001 00000000 00020000

This would translate the model on the y axis as much as the second value in the rotation values, and would rotate the first part of the hierarchy (and all of it's children) as much as the third value of the rotation value list. All of the values left at 0 will do nothing since the first value in the rotation value list is 0.

Animation header

Format:

ffff0000 bbrrrrrr bbiiiiii llll0000

Where:
f is the number of frames in the animation,
b is the segment id
r is the offset of the rotation value list
i is the offset of the rotation index list
l is the limit
Most of these are self explanatory, but there is one that more confusing, the limit. If a entry in the rotation index list is greater than or equal to the limit, then for each frame the next value in the rotation list is read.

Link Animations

Documentation released by Zant Nov 2010

Animation headers

0x2310 to 0x34F8 in gameplay_keep
Format:
ffff0000bboooooo
Where: f is the frame count, b is the segment id, used to reference the file containing the animation (in this case, segment 7 = link_animetion), and o is the offset from the start of the file

Translation

At the offset specified by the header; within link_animetion
Format:
XXXX YYYY ZZZZ
X, Y and Z are all global translation values for this particular frame (signed)

Rotations

The next 0x7E bytes immediately after the translation values are rotation values for each limb, in the order they are listed in the hierarchy. They are rotated on the X, Y, and Z axis, in that order, in 6-byte groups of 2 byte values.
Format:
XXXX YYYY ZZZZ
X, Y and Z are unsigned rotation amounts for the particular limb.

Animated Texture Properties

The last two bytes of an animation frame change Link's facial expression for the current frame. A 16-bit unsigned value. This still needs more research.

Example

Here's the first 0x12 bytes of the first frame of the "Alpha Jump Strike" animation:

0054 00D6 0096 /* XYZ Translation for Link's model for this frame */

C000 FBAC C000 /* XYZ rotation for Link's first limb for this frame */
0000 0000 0000 /* XYZ rotation for Link's second limb for this frame */

Hierarchy

Hierarchies are composed of three chunks: limb entries, limb index, and a header.

Limb entries

Format:

xxxxyyyy zzzzaabb dddddddd [cccccccc*] (repeats for each entry)

* Rare, only used in link
Where:
x is the x translation, relative to the limb's parent
y is the y translation, relative to the limb's parent
z is the z translation, relative to the limb's parent
a is the first child's index in the limb list
b is the next limb's index in the limb list
d is the display list (as a segment offset)
c is the far model display list (as a segment offset)
Example:

00640032 000004FF 06002458

This entry and it's child (entry 4) would be offset by 100 on the x axis, 50 on the y axis, 0 on the x axis. It would render the display list at the offset of 0x2458 within object_link_child (0015, Child Link) or object_link_boy (0014, Adult Link) (the files assigned to segment 6), and it has one child (0x4), 0xFF indicates that there isn't a next limb.

Limb index

Format:

bboooooo (repeats for each entry)

Where:
b is the segment id
o is the offset of the limb entry

Header

Format:

bboooooo pp000000 xx000000

Where:
b is segment id
o is the offset of the beginning of the limb index
p is the number of parts
x is the number of display lists

Beta Format

There is one known file, object_human, which uses a depreciated hierarchy and animation format. ZSaten is capable of viewing these animations as of revision 239. Refer to zold.c for details on implementation of the format.

Hierarchy

Like the supported format, it is a "tree" setup, with child and sibling limbs. Unlike the used format, however, it uses pointers instead of indexes, and contains default rotation values. The translation values are 32-bit floats, as well. The structure for each limb is as follows:

typedef struct {
    Gfx *dl;
    f32 trans[3];
    s16 rot[3];
    u16 __align;
    limb *a;
    limb *b;
} limb;

For people who are not familiar with C structures:

dddddddd xxxxxxxx yyyyyyyy zzzzzzzz qqqqwwww rrrr0000 nnnnnnnn uuuuuuuu

Where d is the display list, x, y, and z are floating-points of the translation values, q, w and r are x/y/z rotation, n is a pointer to the child limb and u is a pointer to the 'sibling' limb.
Besides being pointed to by eachother, all the limbs are pointed to in an array of pointers following them (the limb list). The order they are in this array is the same order that rotations are applied to them during animation.

Animation

The header defines the number of parts in the model and the number of frames in the animation. Format:
ppppffff bbrrrrrr bbiiiiii
Where:
p is the number of parts,
f is the number of frames,
b is the segment id,
r is the rotation values, and
i is the "key".

The rotation values are values referenced by the keys. They are simply unsigned half words representing rotation.
The key is a "lookup" table for the animations. It goes in the order that the limbs are listed in the limb list (as defined above), taking into account that the first "entry" is for translation, not rotation, of limbs. The format is:
aaaaxxxx bbbbyyyy cccczzzz
Where:
a is how many frames there are for x; either 1 or the value of f as defined in the header.
x is which start index of the rotation values to use. If a is 1, x defines the constant rotation index. However, if a is equal to f, x defines the rotation index for the first frame.
b and y are the same as a and x except on the y-axis, as are the c and z pair.


Rendering tips

typedef struct{
    signed short X, Y, Z;
    short XR, YR, ZR;
    char Child;
    char Next;
    unsigned long DList;
} Bone;

void DrawBone(Bones[], int CurrentBone)
{
    glPushMatrix();

    glTranslated(Bones[CurrentBone].X, Bones[CurrentBone].Y, Bones[CurrentBone].Z);
    /* Apply rotation in the order z, y, x! */
    glRotated(Bones[CurrentBone].RZ / 182.0444444, 0, 0, 1);
    glRotated(Bones[CurrentBone].RY / 182.0444444, 0, 1, 0);
    glRotated(Bones[CurrentBone].RX / 182.0444444, 1, 0, 0);

    //Draw display list
    if(Bones[CurrentBone].DList)
        RenderDisplayList(Bones[CurrentBone].DList, true);
    
    //Draw child
    if(Bones[CurrentBone].Child > -1)
        DrawBone(Bones, Bones[CurrentBone].Child);
    
    glPopMatrix(); // pop matrix here!
    
    //Draw next
    if(Bones[CurrentBone].Next > -1)
        DrawBone(Bones, Bones[CurrentBone].Next);
}

Credits

spinout - figuring out most of this stuff initially
euler - filling in the holes in spinout's knowledge
Zant - Link's animation format