From 576653fc04e3b5df1fd0dd895679fcbb439732ab Mon Sep 17 00:00:00 2001
From: DizzyEggg <jajkodizzy@wp.pl>
Date: Thu, 17 Jul 2025 18:59:48 +0200
Subject: [PATCH] more sky map documentation

---
 include/structs/str_ground_bg.h | 11 +++++++++-
 src/ground_bg.c                 | 36 ++++++++++++++++-----------------
 2 files changed, 28 insertions(+), 19 deletions(-)

diff --git a/include/structs/str_ground_bg.h b/include/structs/str_ground_bg.h
index a8f16b739..5a98719ef 100644
--- a/include/structs/str_ground_bg.h
+++ b/include/structs/str_ground_bg.h
@@ -109,10 +109,19 @@ typedef struct LayerSpecs
     s16 numChunks; // Number of chunks in the tilemap + 1. The +1 is the null chunk at the beginning of tile mappings, that is not stored.
 } LayerSpecs;
 
+typedef struct AnimationSpecification
+{
+    s16 durationPerFrame; // Time in game frames to hold a single palette frame for
+    s16 numFrames; // Number of frames. This is also usually the length of frames in animation palette, but it can also be less.
+} AnimationSpecification;
+
 typedef struct BplHeader
 {
     s16 numPalettes;
     s16 hasPalAnimations;
+    // RGB palettes
+    // Animation Specification array
+    // Animation RGB palettes
 } BplHeader;
 
 // size: 0x55C
@@ -131,7 +140,7 @@ typedef struct GroundBg
     LayerSpecs layerSpecs;
     BplHeader bplHeader;
     const void *unk468;
-    const void *unk46C;
+    const AnimationSpecification *animationSpecifications;
     u8 unk470;
     u8 unk471;
     s32 unk474;
diff --git a/src/ground_bg.c b/src/ground_bg.c
index 21ad7f4ee..06b2b37a7 100644
--- a/src/ground_bg.c
+++ b/src/ground_bg.c
@@ -78,7 +78,7 @@ void GroundBg_Init(GroundBg *groundBg, const SubStruct_52C *a1)
     groundBg->bmaHeader.mapWidthChunks = 0;
     groundBg->bmaHeader.mapHeightChunks = 0;
     unk0Ptr = &groundBg->unk0[0];
-    groundBg->unk46C = 0;
+    groundBg->animationSpecifications = 0;
     groundBg->unk470 = 0;
     groundBg->unk471 = 0;
 
@@ -172,7 +172,7 @@ void sub_80A2E64(GroundBg *groundBg)
     groundBg->bmaHeader.mapWidthChunks = 0;
     groundBg->bmaHeader.mapHeightChunks = 0;
     unk0Ptr = &groundBg->unk0[0];
-    groundBg->unk46C = 0;
+    groundBg->animationSpecifications = NULL;
     groundBg->unk470 = 0;
     groundBg->unk471 = 0;
 
@@ -308,17 +308,17 @@ void sub_80A2FBC(GroundBg *groundBg, s32 mapFileId_)
 
     sub0Ptr = groundBg->unk0;
     unk0Id = 0;
-    if (bplHeader->hasPalAnimations != 0) {
-        const s16 *r3 = bplData + (bplHeader->numPalettes * 60);
-        const void *r6 = &r3[bplHeader->numPalettes * 2];
+    if (bplHeader->hasPalAnimations) {
+        const AnimationSpecification *animSpecifications = bplData + (bplHeader->numPalettes * 60);
+        const RGB_Array *animationPalette = ((void *) animSpecifications) + bplHeader->numPalettes * 4;
 
-        groundBg->unk46C = r3;
+        groundBg->animationSpecifications = animSpecifications;
         groundBg->unk470 = 1;
         groundBg->unk471 = 1;
-        for (; unk0Id < bplHeader->numPalettes && unk0Id < groundBg->unk52C.unk2; unk0Id++, sub0Ptr++, r3 += 2) {
-            if (r3[1] > 0) {
-                sub0Ptr->unk4 = r6;
-                r6 += r3[1] * 60;
+        for (; unk0Id < bplHeader->numPalettes && unk0Id < groundBg->unk52C.unk2; unk0Id++, sub0Ptr++, animSpecifications++) {
+            if (animSpecifications->numFrames > 0) {
+                sub0Ptr->unk4 = animationPalette;
+                animationPalette += animSpecifications->numFrames * 15;
             }
             else {
                 sub0Ptr->unk4 = NULL;
@@ -329,7 +329,7 @@ void sub_80A2FBC(GroundBg *groundBg, s32 mapFileId_)
         }
     }
     else {
-        groundBg->unk46C = NULL;
+        groundBg->animationSpecifications = NULL;
         groundBg->unk470 = 0;
         groundBg->unk471 = 0;
     }
@@ -507,7 +507,7 @@ void sub_80A3440(GroundBg *groundBg, s32 mapFileId_, const DungeonLocation *dung
     if (groundBg->unk440 != NULL) {
         sub_8004AA4(groundBg->unkE0, groundBg->unk440, UNK_E0_ARR_COUNT);
     }
-    groundBg->unk46C = NULL;
+    groundBg->animationSpecifications = NULL;
     groundBg->unk470 = 0;
     groundBg->unk471 = 0;
 
@@ -684,7 +684,7 @@ static const u8 *BmaLayerNrlDecompressor(u16 **dstArray, const void *bmaData, Su
 
 void sub_80A3B80(GroundBg *groundBg, u8 a1, u8 a2)
 {
-    if (groundBg->unk46C != NULL) {
+    if (groundBg->animationSpecifications != NULL) {
         groundBg->unk470 = a1;
         groundBg->unk471 = a2;
     }
@@ -1338,15 +1338,15 @@ void sub_80A4764(GroundBg *groundBg)
     if (groundBg->bplHeader.hasPalAnimations) {
         s32 i;
         SubStruct_0 *sub0Ptr = groundBg->unk0;
-        const s16 *ptr = groundBg->unk46C;
+        const AnimationSpecification *animSpecifications = groundBg->animationSpecifications;
         u16 r6 = groundBg->unk52C.unk0 * 16;
 
-        for (i = 0; i < groundBg->bplHeader.numPalettes; i++, sub0Ptr++, ptr += 2, r6 += 16) {
+        for (i = 0; i < groundBg->bplHeader.numPalettes; i++, sub0Ptr++, animSpecifications++, r6 += 16) {
             if (sub0Ptr->unk4 != NULL && --sub0Ptr->unk2 <= 0) {
                 if (--sub0Ptr->unk0 <= 0) {
                     if (groundBg->unk471) {
-                        sub0Ptr->unk2 = ptr[0];
-                        sub0Ptr->unk0 = ptr[1];
+                        sub0Ptr->unk2 = animSpecifications->durationPerFrame;
+                        sub0Ptr->unk0 = animSpecifications->numFrames;
                         sub0Ptr->unk8 = sub0Ptr->unk4;
                     }
                     else {
@@ -1356,7 +1356,7 @@ void sub_80A4764(GroundBg *groundBg)
                     }
                 }
                 else {
-                    sub0Ptr->unk2 = ptr[0];
+                    sub0Ptr->unk2 = animSpecifications->durationPerFrame;
                 }
 
                 if (sub0Ptr->unk8 != NULL) {