ovl_En_Test5 (Spring Water Modifier) OK with attempted documentation (#483)

* Implement asm functions in C

* Clean up code with documentation

* Apply styling suggestions

* Apply feedback

spec

@@ -3233,8 +3233,7 @@ beginseg
     name "ovl_En_Test5"
     compress
     include "build/src/overlays/actors/ovl_En_Test5/z_en_test5.o"
-    include "build/data/ovl_En_Test5/ovl_En_Test5.data.o"
-    include "build/data/ovl_En_Test5/ovl_En_Test5.reloc.o"
+    include "build/src/overlays/actors/ovl_En_Test5/ovl_En_Test5_reloc.o"
 endseg
 
 beginseg

src/overlays/actors/ovl_En_Test5/z_en_test5.c

@@ -1,7 +1,7 @@
 /*
  * File: z_en_test5.c
  * Overlay: ovl_En_Test5
- * Description: Spring Water
+ * Description: Spring Water Modifier
  */
 
 #include "z_en_test5.h"
@@ -13,12 +13,9 @@
 void EnTest5_Init(Actor* thisx, GlobalContext* globalCtx);
 void EnTest5_Destroy(Actor* thisx, GlobalContext* globalCtx);
 void EnTest5_Update(Actor* thisx, GlobalContext* globalCtx);
-
-void func_80A90478(EnTest5* this, GlobalContext* globalCtx);
-
+void EnTest5_HandleBottleAction(EnTest5* this, GlobalContext* globalCtx);
 void EnTest5_SetupAction(EnTest5* this, EnTest5ActionFunc actionFunc);
 
-#if 0
 const ActorInit En_Test5_InitVars = {
     ACTOR_EN_TEST5,
     ACTORCAT_ITEMACTION,
@@ -31,14 +28,82 @@ const ActorInit En_Test5_InitVars = {
     (ActorFunc)NULL,
 };
 
-#endif
+void EnTest5_SetupAction(EnTest5* this, EnTest5ActionFunc actionFunc) {
+    this->actionFunc = actionFunc;
+}
 
-#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Test5/EnTest5_SetupAction.s")
+void EnTest5_Init(Actor* thisx, GlobalContext* globalCtx2) {
+    EnTest5* this = THIS;
+    GlobalContext* globalCtx = globalCtx2;
+    WaterBox* water;
+    f32 ySurface; // Unused
 
-#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Test5/EnTest5_Init.s")
+    // If not spawned above a water source, immediately despawn
+    if (!WaterBox_GetSurface1(globalCtx, &globalCtx->colCtx, this->actor.world.pos.x, this->actor.world.pos.z,
+                              &ySurface, &water)) {
+        Actor_MarkForDeath(&this->actor);
+        return;
+    }
 
-#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Test5/EnTest5_Destroy.s")
+    Math_Vec3s_ToVec3f(&this->minPos, &water->minPos);
+    this->xLength = (f32)water->xLength;
+    this->zLength = (f32)water->zLength;
 
-#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Test5/func_80A90478.s")
+    EnTest5_SetupAction(this, EnTest5_HandleBottleAction);
+}
 
-#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Test5/EnTest5_Update.s")
+void EnTest5_Destroy(Actor* thisx, GlobalContext* globalCtx) {
+}
+
+void EnTest5_HandleBottleAction(EnTest5* this, GlobalContext* globalCtx) {
+    Player* player;
+    Vec3f playerPosRelativeToWater;
+
+    if (Actor_HasParent(&this->actor, globalCtx)) {
+        this->actor.parent = NULL;
+        return;
+    }
+
+    player = GET_PLAYER(globalCtx);
+
+    if (player->unk_388 == NULL || player->unk_384 != GI_MAX) {
+        Math_Vec3f_DistXYZAndStoreDiff(&this->minPos, &player->actor.world.pos, &playerPosRelativeToWater);
+
+        // Make sure that the player is within the bounds of the water and deep enough to grab some
+        if (playerPosRelativeToWater.x >= 0.0f && playerPosRelativeToWater.x <= this->xLength &&
+            playerPosRelativeToWater.z >= 0.0f && playerPosRelativeToWater.z <= this->zLength &&
+            fabsf(playerPosRelativeToWater.y) < 100.0f && player->actor.depthInWater > 12.0f) {
+            func_800B8A1C(&this->actor, globalCtx, GI_MAX, this->actor.xzDistToPlayer,
+                          fabsf(this->actor.playerHeightRel));
+        }
+    }
+}
+
+void EnTest5_Update(Actor* thisx, GlobalContext* globalCtx2) {
+    EnTest5* this = THIS;
+    GlobalContext* globalCtx = globalCtx2;
+    Vec3f steamPos;
+    CollisionPoly* poly; // Unused
+    s32 pad;             // Unused
+
+    this->actionFunc(this, globalCtx);
+
+    // If it's the hot spring variant, generate steam clouds
+    if (ENTEST5_IS_HOT_SPRING(&this->actor) && (globalCtx->state.frames % 4) == 0) {
+        steamPos.x = (Rand_ZeroOne() * this->xLength) + this->minPos.x;
+        steamPos.y = this->minPos.y + 100.0f;
+        steamPos.z = (Rand_ZeroOne() * this->zLength) + this->minPos.z;
+
+        if ((BgCheck_EntityRaycastFloor2(globalCtx, &globalCtx->colCtx, &poly, &steamPos) + 10.0f) < this->minPos.y) {
+            Vec3f steamVel;
+
+            steamPos.y = this->minPos.y + 10.0f;
+            steamVel.y = 0.5f;
+            steamVel.x = 0.0f;
+            steamVel.z = 0.0f;
+
+            EffectSsIceSmoke_Spawn(globalCtx, &steamPos, &steamVel, &D_801D15B0,
+                                   (s16)((-200) - (s32)(Rand_ZeroOne() * 50.0f)));
+        }
+    }
+}

src/overlays/actors/ovl_En_Test5/z_en_test5.h

@@ -3,14 +3,18 @@
 
 #include "global.h"
 
-struct EnTest5;
+#define ENTEST5_IS_HOT_SPRING(thisx) ((thisx)->params != 0)
+
+struct EnTest5; // SpringWaterModifier
 
 typedef void (*EnTest5ActionFunc)(struct EnTest5*, GlobalContext*);
 
 typedef struct EnTest5 {
     /* 0x0000 */ Actor actor;
-    /* 0x0144 */ char unk_144[0x14];
-    /* 0x0158 */ EnTest5ActionFunc actionFunc;
+    /* 0x0144 */ Vec3f minPos;
+    /* 0x0150 */ f32 xLength;
+    /* 0x0154 */ f32 zLength;
+    /* 0x0158 */ EnTest5ActionFunc actionFunc;    
 } EnTest5; // size = 0x15C
 
 extern const ActorInit En_Test5_InitVars;

tools/disasm/functions.txt

@@ -11336,7 +11336,7 @@
     0x80A903B0:("EnTest5_SetupAction",),
     0x80A903BC:("EnTest5_Init",),
     0x80A90468:("EnTest5_Destroy",),
-    0x80A90478:("func_80A90478",),
+    0x80A90478:("EnTest5_HandleBottleAction",),
     0x80A905A4:("EnTest5_Update",),
     0x80A90730:("func_80A90730",),
     0x80A90C08:("func_80A90C08",),