From aaee5b750e5602895da6190f70ccc6597e507123 Mon Sep 17 00:00:00 2001
From: Jeremy Penner <jeremy@sporktania.com>
Date: Thu, 28 Dec 2023 09:14:33 -0500
Subject: [PATCH] Improve documentation of avatar format

---
 avatars.md | 50 ++++++++++++++++++++++++++++++++++----------------
 index.js   |  1 +
 2 files changed, 35 insertions(+), 16 deletions(-)

diff --git a/avatars.md b/avatars.md
index e0c95b1..de8be42 100644
--- a/avatars.md
+++ b/avatars.md
@@ -1,10 +1,11 @@
-; 0 - number of animation bytes (WRONG? 0x16 in file)
-; 1 - disk_face (byte)
-; 3 - bits for cels to draw
+; Avatar file:
+; 0-1 - offset to choreography index
+; 2-3 - offset to choreography tables
+; 4-6 - unknown, seems to always be ED 14 00
+; 7-18 - offsets of limbs (two bytes each, 6 limbs)
 
-; 7 - offsets of embedded props for limbs (two bytes each, 6 limbs)
-
-; 19: display_avatar copies _26 bytes_
+; 19-44 - as follows
+; (display_avatar in animate.m:30 copies 26 bytes into these tables)
 
 head_cel_number:
 	byte	4
@@ -24,19 +25,36 @@ fv_cels:					; order of cels front view
 bv_cels:
 	byte	5,2,4,0,1,3
 
-limbs_affected_by_height:
+cels_affected_by_height:
 	byte	0,0,1,1,1,1
 
+; "cel" here doesn't mean "cel" in the data structure sense, as each limb 
+; can have many different cels. however, only one cel per limb is 
+; displayed at any given time.
+
+; avatar_height is defined in orientation - either 0 or 8 depending on the high bit
+
 ; limbs are _embedded_ props?? animate.m get_av_prop_address
 (A * 2) + 8 - high byte of offset!!
 
-avatars can have up to 16 cels - each frame is _only_ 1 cel, rather than a composite
-byte_to_bit lookup table turns it into a bitmask, used by cels_to_draw_2 & cels_to_draw
 
-; embedded limb "prop":
-; 0 - number of animation bytes A
-; 1 - unk
-; 2 - unk
-; 3:A+2 - first 
-; A+3 - unk
-; A+4:A+20 - cel offsets (Word)
+; limb "prop":
+; 0 - count of cel index "frames", minus one 
+
+; limbs can have up to 16 cels. therefore, instead of defining states as
+; an index into a table of bitmasks, states are defined as an index into
+; the table of cels directly. only one cel is visible per-limb at a time.
+
+; 1-2 - unknown. first byte seems to always be zero. second byte seems
+;   to be correlated with the number of frames or cels, but isn't a direct
+;   count of either.
+; 3 - list of "frames" (cel indexes), (count + 1) bytes long
+; (count + 4) - list of cel offsets (two-byte values)
+
+; cels are in exactly the same format as in props.
+
+; choreography index:
+; TBD
+
+; choreography tables:
+; TBD
\ No newline at end of file
diff --git a/index.js b/index.js
index f5b90e8..5001b78 100644
--- a/index.js
+++ b/index.js
@@ -477,6 +477,7 @@ const decodeProp = (data) => {
 }
 
 const decodeLimb = (data, limb) => {
+    limb.unknown = [data.getUint8(1), data.getUint8(2)]
     let frameCount = data.getUint8(0) + 1
     limb.frames = []
     for (let iframe = 0; iframe < frameCount; iframe ++) {