Animation Format - Revision history

Jrra: /* Beta Format */ FIx broken link

2023-02-23T21:23:14Z

‎Beta Format: FIx broken link

CrookedPoe: /* Link Animations */

2019-10-28T05:35:08Z

‎Link Animations

Mzxrules: /* Animation header */

2018-03-03T10:39:10Z

‎Animation header

Mzxrules at 00:35, 7 November 2016

2016-11-07T00:35:21Z

Mzxrules: 1 revision

2014-06-08T23:21:04Z

1 revision

Spinout at 00:52, 27 September 2011

2011-09-27T00:52:02Z

New page

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]], [[OZMAV|OZMAV2]] and [[z64anim]] are all viewers which can render normal skeletal structures ([[#Hierachy|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 bank 
'''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 explanitory, 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: 
<tt>ffff0000bboooooo</tt> 
Where:
'''f''' is the frame count, '''b''' is the bank containing the animation (bank 7 = '''link_animetion'''), and '''o''' is the offset in that bank
===Translation===
At the offset specified by the header; within link_animetion 
Format: 
<tt>XXXX YYYY ZZZZ</tt> 
'''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: 
<tt>XXXX YYYY ZZZZ</tt> 
'''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:
<pre>
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 */
</pre>

==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)
<nowiki>*</nowiki> 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 (bank and offset) 
'''c''' is the far model display list (bank and 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 bank 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 bank 
'''o''' is the offset of the limb entry 

===Header===
Format:
bboooooo pp000000 xx000000
Where: 
'''b''' is bank 
'''o''' is the offset of the beggining 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 [http://code.google.com/p/ozmav/source/detail?r=239 revision 239]. Refer to [http://ozmav.googlecode.com/svn/trunk/zsaten/zold.c 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:
<pre>typedef struct {
Gfx *dl;
f32 trans[3];
s16 rot[3];
u16 __align;
limb *a;
limb *b;
} limb;</pre>
For people who are not familiar with C structures:
<pre>dddddddd xxxxxxxx yyyyyyyy zzzzzzzz qqqqwwww rrrr0000 nnnnnnnn uuuuuuuu</pre>
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: 
<tt>ppppffff bbrrrrrr bbiiiiii</tt> 
Where: 
'''p''' is the number of parts, 
'''f''' is the number of frames, 
'''b''' is the bank, 
'''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: 
<tt>aaaaxxxx bbbbyyyy cccczzzz</tt> 
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==
<pre>
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);
}
</pre>

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

[[Category: File Formats]]
[[Category: Documentation]]

@@ Line 21: / Line 21: @@
 ===Animation header===
 Format:
-  ffff0000 bbrrrrrr bbiiiiii llll0000
+  ffff0000 rrrrrrrr iiiiiiii llll0000
 Where:<br>
-'''f''' is the number of frames in the animation,<br>
+* '''f''' is the number of frames in the animation
-'''b''' is the segment id<br>
+* '''r''' is the segment offset of the rotation value list
-'''r''' is the offset of the rotation value list<br>
+* '''i''' is the segment offset of the rotation index list
-'''i''' is the offset of the rotation index list<br>
+* '''l''' is the limit
-'''l''' is the limit<br>
 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''

@@ Line 24: / Line 24: @@
 Where:<br>
 '''f''' is the number of frames in the animation,<br>
-'''b''' is the bank<br>
+'''b''' is the segment id<br>
 '''r''' is the offset of the rotation value list<br>
 '''i''' is the offset of the rotation index list<br>
 '''l''' is the limit<br>
-Most of these are self explanitory, 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.
+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''
@@ Line 36: / Line 36: @@
 <tt>ffff0000bboooooo</tt><br>
 Where:
-'''f''' is the frame count, '''b''' is the bank containing the animation (bank 7 = '''link_animetion'''), and '''o''' is the offset in that bank
+'''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<br>
@@ Line 72: / Line 72: @@
 '''a''' is the first child's index in the limb list<br>
 '''b''' is the next limb's index in the limb list<br>
-'''d''' is the display list (bank and offset)<br>
+'''d''' is the display list (as a [[segment offset]])<br>
-'''c''' is the far model display list (bank and offset)<br>
+'''c''' is the far model display list (as a [[segment offset]])<br>
 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 bank 6, and it has one child (0x4), 0xFF indicates that there isn't a next limb.
+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 ref|object_link_child}} or {{object ref|14}} (the files assigned to segment 6), and it has one child (0x4), 0xFF indicates that there isn't a next limb.
 ===Limb index===
@@ Line 82: / Line 82: @@
   bboooooo (repeats for each entry)
 Where:<br>
-'''b''' is the bank<br>
+'''b''' is the segment id<br>
 '''o''' is the offset of the limb entry<br>
@@ Line 89: / Line 89: @@
   bboooooo pp000000 xx000000
 Where:<br>
-'''b''' is bank<br>
+'''b''' is segment id<br>
-'''o''' is the offset of the beggining of the limb index<br>
+'''o''' is the offset of the beginning of the limb index<br>
 '''p''' is the number of parts<br>
 '''x''' is the number of display lists<!--Really? It is often set to 0. I should see how the engine treats the value--><br>
@@ Line 116: / Line 116: @@
 '''p''' is the number of parts,<br>
 '''f''' is the number of frames,<br>
-'''b''' is the bank,<br>
+'''b''' is the segment id,<br>
 '''r''' is the rotation values, and<br>
 '''i''' is the "key".<br>

@@ Line 182: / Line 182: @@
 '''x''' is the number of display lists<!--Really? It is often set to 0. I should see how the engine treats the value--><br>
 ==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 [http://code.google.com/p/ozmav/source/detail?r=239 revision 239]. Refer to [http://ozmav.googlecode.com/svn/trunk/zsaten/zold.c zold.c] for details on implementation of the format.
+There is one known file, object_human, which uses a depreciated hierarchy and animation format. [[ZSaten]] is capable of viewing these animations. Refer to [https://github.com/xdanieldzd/ozmav/blob/master/zsaten/zold.c 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:

@@ Line 59: / Line 59: @@
 C000 FBAC C000 /* XYZ rotation for Link's first limb for this frame */
 0000 0000 /* XYZ rotation for Link's second limb for this frame */
 </pre>

← Older revision	Revision as of 23:21, 8 June 2014
(No difference)