From 4b10b22baabfaf1753d7d7cc2d7339579ee05ed6 Mon Sep 17 00:00:00 2001
From: Dragorn421 <Dragorn421@users.noreply.github.com>
Date: Sat, 23 Oct 2021 03:28:16 +0200
Subject: [PATCH] Document object_pu_box and related actors (#918)

* object_pu_box-related doc

* Cleanup undefined_syms.txt
---
 assets/xml/objects/object_pu_box.xml           | 18 +++++++++---------
 .../actors/ovl_Bg_Pushbox/z_bg_pushbox.c       | 17 ++++++++---------
 .../actors/ovl_En_Pu_box/z_en_pu_box.c         |  4 ++--
 undefined_syms.txt                             |  4 ----
 4 files changed, 19 insertions(+), 24 deletions(-)

diff --git a/assets/xml/objects/object_pu_box.xml b/assets/xml/objects/object_pu_box.xml
index df9f8e25a7..e1d686e979 100644
--- a/assets/xml/objects/object_pu_box.xml
+++ b/assets/xml/objects/object_pu_box.xml
@@ -1,13 +1,13 @@
 <Root>
     <File Name="object_pu_box" Segment="6">
-        <DList Name="gUnknownUnusedBox1DL" Offset="0x0"/>
-        <Collision Name="gUnknownUnusedBox1Col" Offset="0x350"/>
-        <DList Name="gUnknownUnusedBox2DL" Offset="0x380"/>
-        <Collision Name="gUnknownUnusedBox2Col" Offset="0x6D0"/>
-        <DList Name="gUnknownUnusedBox3DL" Offset="0x700"/>
-        <Collision Name="gUnknownUnusedBox3Col" Offset="0xA50"/>
-        <DList Name="gUnknownUnusedBox4DL" Offset="0xA80"/>
-        <Collision Name="gUnknownUnusedBox4Col" Offset="0x15D0"/>
-        <Texture Name="gUnknownUnusedBoxTex" OutName="unknown_unused_box" Format="rgba16" Width="32" Height="32" Offset="0xCC8"/>
+        <DList Name="gBlockSmallDL" Offset="0x0"/>
+        <Collision Name="gBlockSmallCol" Offset="0x350"/>
+        <DList Name="gBlockMediumDL" Offset="0x380"/>
+        <Collision Name="gBlockMediumCol" Offset="0x6D0"/>
+        <DList Name="gBlockTallDL" Offset="0x700"/>
+        <Collision Name="gBlockTallCol" Offset="0xA50"/>
+        <DList Name="gBlockTallestDL" Offset="0xA80"/>
+        <Collision Name="gBlockTallestCol" Offset="0x15D0"/>
+        <Texture Name="gBlockTex" OutName="block" Format="rgba16" Width="32" Height="32" Offset="0xCC8"/>
     </File>
 </Root>
diff --git a/src/overlays/actors/ovl_Bg_Pushbox/z_bg_pushbox.c b/src/overlays/actors/ovl_Bg_Pushbox/z_bg_pushbox.c
index aa179c6371..7b07d0d840 100644
--- a/src/overlays/actors/ovl_Bg_Pushbox/z_bg_pushbox.c
+++ b/src/overlays/actors/ovl_Bg_Pushbox/z_bg_pushbox.c
@@ -1,10 +1,11 @@
 /*
  * File: z_bg_pushbox.c
  * Overlay: ovl_Bg_Pushbox
- * Description:
+ * Description: Unused (and non functional) pushable block
  */
 
 #include "z_bg_pushbox.h"
+#include "objects/object_pu_box/object_pu_box.h"
 
 #define FLAGS 0x00000000
 
@@ -15,12 +16,13 @@ void BgPushbox_Destroy(Actor* thisx, GlobalContext* globalCtx);
 void BgPushbox_Update(Actor* thisx, GlobalContext* globalCtx);
 void BgPushbox_Draw(Actor* thisx, GlobalContext* globalCtx);
 
-void func_808A8BAC(BgPushbox* this, GlobalContext* globalCtx);
+void BgPushbox_UpdateImpl(BgPushbox* this, GlobalContext* globalCtx);
 
 const ActorInit Bg_Pushbox_InitVars = {
     ACTOR_BG_PUSHBOX,
     ACTORCAT_BG,
     FLAGS,
+    //! @bug fixing this actor would involve using OBJECT_PU_BOX
     OBJECT_GAMEPLAY_DANGEON_KEEP,
     sizeof(BgPushbox),
     (ActorFunc)BgPushbox_Init,
@@ -29,9 +31,6 @@ const ActorInit Bg_Pushbox_InitVars = {
     (ActorFunc)BgPushbox_Draw,
 };
 
-extern Gfx D_06000000[];
-extern CollisionHeader D_06000350;
-
 static InitChainEntry sInitChain[] = {
     ICHAIN_F32_DIV1000(gravity, -2000, ICHAIN_STOP),
 };
@@ -48,10 +47,10 @@ void BgPushbox_Init(Actor* thisx, GlobalContext* globalCtx) {
 
     Actor_ProcessInitChain(&this->dyna.actor, sInitChain);
     DynaPolyActor_Init(&this->dyna, DPM_UNK);
-    CollisionHeader_GetVirtual(&D_06000350, &colHeader);
+    CollisionHeader_GetVirtual(&gBlockSmallCol, &colHeader);
     this->dyna.bgId = DynaPoly_SetBgActor(globalCtx, &globalCtx->colCtx.dyna, &this->dyna.actor, colHeader);
     ActorShape_Init(&this->dyna.actor.shape, 0.0f, NULL, 0.0f);
-    BgPushbox_SetupAction(this, func_808A8BAC);
+    BgPushbox_SetupAction(this, BgPushbox_UpdateImpl);
 }
 
 void BgPushbox_Destroy(Actor* thisx, GlobalContext* globalCtx) {
@@ -60,7 +59,7 @@ void BgPushbox_Destroy(Actor* thisx, GlobalContext* globalCtx) {
     DynaPoly_DeleteBgActor(globalCtx, &globalCtx->colCtx.dyna, this->dyna.bgId);
 }
 
-void func_808A8BAC(BgPushbox* this, GlobalContext* globalCtx) {
+void BgPushbox_UpdateImpl(BgPushbox* this, GlobalContext* globalCtx) {
     this->dyna.actor.speedXZ += this->dyna.unk_150 * 0.2f;
     this->dyna.actor.speedXZ = (this->dyna.actor.speedXZ < -1.0f)
                                    ? -1.0f
@@ -86,7 +85,7 @@ void BgPushbox_Draw(Actor* thisx, GlobalContext* globalCtx) {
     func_80093D18(globalCtx->state.gfxCtx);
     gSPMatrix(POLY_OPA_DISP++, Matrix_NewMtx(globalCtx->state.gfxCtx, "../z_bg_pushbox.c", 269),
               G_MTX_NOPUSH | G_MTX_MODELVIEW | G_MTX_LOAD);
-    gSPDisplayList(POLY_OPA_DISP++, &D_06000000);
+    gSPDisplayList(POLY_OPA_DISP++, &gBlockSmallDL);
 
     CLOSE_DISPS(globalCtx->state.gfxCtx, "../z_bg_pushbox.c", 272);
 }
diff --git a/src/overlays/actors/ovl_En_Pu_box/z_en_pu_box.c b/src/overlays/actors/ovl_En_Pu_box/z_en_pu_box.c
index 22745408f7..97064fda3e 100644
--- a/src/overlays/actors/ovl_En_Pu_box/z_en_pu_box.c
+++ b/src/overlays/actors/ovl_En_Pu_box/z_en_pu_box.c
@@ -57,7 +57,7 @@ void EnPubox_Init(Actor* thisx, GlobalContext* globalCtx) {
     this->dyna.unk_15C = DPM_UNK;
     thisx->targetMode = 1;
     thisx->gravity = -2.0f;
-    CollisionHeader_GetVirtual(&gUnknownUnusedBox2Col, &colHeader);
+    CollisionHeader_GetVirtual(&gBlockMediumCol, &colHeader);
     this->dyna.bgId = DynaPoly_SetBgActor(globalCtx, &globalCtx->colCtx.dyna, thisx, colHeader);
 }
 
@@ -87,5 +87,5 @@ void EnPubox_Update(Actor* thisx, GlobalContext* globalCtx) {
 }
 
 void EnPubox_Draw(Actor* thisx, GlobalContext* globalCtx) {
-    Gfx_DrawDListOpa(globalCtx, gUnknownUnusedBox2DL);
+    Gfx_DrawDListOpa(globalCtx, gBlockMediumDL);
 }
diff --git a/undefined_syms.txt b/undefined_syms.txt
index 9cf6a92c01..fbd1030cf0 100644
--- a/undefined_syms.txt
+++ b/undefined_syms.txt
@@ -90,10 +90,6 @@ D_01000000 = 0x01000000;
 D_0602B288 = 0x0602B288;
 D_0602AFF0 = 0x0602AFF0;
 
-// z_bg_pushbox
-D_06000000 = 0x06000000;
-D_06000350 = 0x06000350;
-
 // code_800AD920
 D_0E000000 = 0x0E000000;