Document Player's bgcheck routine (#1275)

* Thanks Fig

* cleanup

* more docs

* cleanup

* oops

* cleanup comment

* add comment to SurfaceType_GetSceneExitIndex

* fix bss

include/z64bgcheck.h

@@ -223,6 +223,8 @@ typedef enum ConveyorSpeed {
     /* 4 */ CONVEYOR_SPEED_MAX
 } ConveyorSpeed;
 
+#define CONVEYOR_DIRECTION_TO_BINANG(conveyorDirection) ((conveyorDirection) * (0x10000 / 64))
+
 typedef struct {
     /* 0x0 */ u32 data[2];
 

include/z64player.h

@@ -524,22 +524,32 @@ typedef struct PlayerAnimationFrame {
 #define GET_LEFT_HAND_INDEX_FROM_JOINT_TABLE(jointTable)   (GET_APPEARANCE_FROM_JOINT_TABLE(jointTable) & 0xF000)
 #define GET_RIGHT_HAND_INDEX_FROM_JOINT_TABLE(jointTable)  (GET_APPEARANCE_FROM_JOINT_TABLE(jointTable) & 0x0F00)
 
+typedef enum PlayerLedgeClimbType {
+    /* 0 */ PLAYER_LEDGE_CLIMB_NONE,
+    /* 1 */ PLAYER_LEDGE_CLIMB_1,
+    /* 2 */ PLAYER_LEDGE_CLIMB_2,
+    /* 3 */ PLAYER_LEDGE_CLIMB_3,
+    /* 4 */ PLAYER_LEDGE_CLIMB_4
+} PlayerLedgeClimbType;
+
+#define LEDGE_DIST_MAX 399.96002f
+
 typedef struct PlayerAgeProperties {
-    /* 0x00 */ f32 unk_00; // ceilingCheckHeight
+    /* 0x00 */ f32 ceilingCheckHeight;
     /* 0x04 */ f32 shadowScale;
     /* 0x08 */ f32 unk_08;
     /* 0x0C */ f32 unk_0C;
     /* 0x10 */ f32 unk_10;
-    /* 0x14 */ f32 unk_14; // compared to wallHeight
-    /* 0x18 */ f32 unk_18; // compared to wallHeight
-    /* 0x1C */ f32 unk_1C; // compared to wallHeight
+    /* 0x14 */ f32 unk_14; // compared to yDistToLedge
+    /* 0x18 */ f32 unk_18; // compared to yDistToLedge
+    /* 0x1C */ f32 unk_1C; // compared to yDistToLedge
     /* 0x20 */ f32 unk_20; // unused?
     /* 0x24 */ f32 unk_24; // water stuff // depthInWater
     /* 0x28 */ f32 unk_28; // water stuff // depthInWater
     /* 0x2C */ f32 unk_2C; // water stuff // depthInWater
     /* 0x30 */ f32 unk_30; // water stuff // depthInWater
-    /* 0x34 */ f32 unk_34;
-    /* 0x38 */ f32 unk_38; // wallCheckHeight
+    /* 0x34 */ f32 unk_34; // height?
+    /* 0x38 */ f32 wallCheckRadius;
     /* 0x3C */ f32 unk_3C;
     /* 0x40 */ f32 unk_40;
     /* 0x44 */ Vec3s unk_44;
@@ -819,7 +829,7 @@ typedef enum PlayerCsMode {
 // 
 #define PLAYER_STATE2_100        (1 << 8)
 // 
-#define PLAYER_STATE2_200        (1 << 9)
+#define PLAYER_STATE2_FORCE_SAND_FLOOR_SOUND (1 << 9)
 // 
 #define PLAYER_STATE2_400        (1 << 10)
 // Diving
@@ -1130,10 +1140,10 @@ typedef struct Player {
     /* 0xB4C */ s16 unk_B4C;
     /* 0xB4E */ s16 unk_B4E;
     /* 0xB50 */ f32 unk_B50;
-    /* 0xB54 */ f32 wallHeight; // height used to determine whether link can climb or grab a ledge at the top
-    /* 0xB58 */ f32 wallDistance; // distance to the colliding wall plane
-    /* 0xB5C */ u8 unk_B5C;
-    /* 0xB5D */ u8 unk_B5D;
+    /* 0xB54 */ f32 yDistToLedge; // y distance to ground above an interact wall. LEDGE_DIST_MAX if no ground if found
+    /* 0xB58 */ f32 distToInteractWall; // xyz distance to the interact wall
+    /* 0xB5C */ u8 ledgeClimbType; // see PlayerLedgeClimbType enum
+    /* 0xB5D */ u8 ledgeClimbDelayTimer;
     /* 0xB5E */ u8 unk_B5E;
     /* 0xB5F */ u8 unk_B5F;
     /* 0xB60 */ u16 blastMaskTimer;
@@ -1144,8 +1154,8 @@ typedef struct Player {
     /* 0xB67 */ u8 remainingHopsCounter; // Deku hopping on water
     /* 0xB68 */ s16 fallStartHeight; // last truncated Y position before falling
     /* 0xB6A */ s16 fallDistance; // truncated Y distance the player has fallen so far (positive is down)
-    /* 0xB6C */ s16 unk_B6C;
-    /* 0xB6E */ s16 unk_B6E;
+    /* 0xB6C */ s16 floorPitch; // angle of the floor slope in the direction of current world yaw (positive for ascending slope)
+    /* 0xB6E */ s16 floorPitchAlt; // the calculation for this value is bugged and doesn't represent anything meaningful
     /* 0xB70 */ s16 unk_B70;
     /* 0xB72 */ u16 floorSfxOffset;
     /* 0xB74 */ u8 unk_B74;
@@ -1172,11 +1182,12 @@ typedef struct Player {
     /* 0xD57 */ u8 unk_D57;
     /* 0xD58 */ PlayerFuncD58 unk_D58;
     /* 0xD5C */ s8 invincibilityTimer; // prevents damage when nonzero (positive = visible, counts towards zero each frame)
-    /* 0xD5D */ u8 unk_D5D;
+    /* 0xD5D */ u8 floorTypeTimer; // Unused remnant of OoT
     /* 0xD5E */ u8 floorProperty; // FloorProperty enum
+    /* 0xD5F */ u8 prevFloorType; // Unused remnant of OoT
     /* 0xD60 */ f32 unk_D60;
     /* 0xD64 */ s16 unk_D64;
-    /* 0xD66 */ u16 unk_D66; // sfx
+    /* 0xD66 */ u16 prevFloorSfxOffset;
     /* 0xD68 */ s16 unk_D68;
     /* 0xD6A */ s8 unk_D6A;
     /* 0xD6B */ u8 unk_D6B;

src/code/z_bgcheck.c

@@ -4200,6 +4200,9 @@ Vec3s* BgCheck_GetBgCamFuncData(CollisionContext* colCtx, CollisionPoly* poly, s
     return BgCheck_GetBgCamFuncDataImpl(colCtx, SurfaceType_GetBgCamIndex(colCtx, poly, bgId), bgId);
 }
 
+/**
+ * Returns one above the value indexed by `play->setupExitList[]`
+ */
 u32 SurfaceType_GetSceneExitIndex(CollisionContext* colCtx, CollisionPoly* poly, s32 bgId) {
     return SurfaceType_GetData(colCtx, poly, bgId, 0) >> 8 & 0x1F;
 }

src/overlays/actors/ovl_En_Bomjimb/z_en_bomjimb.c

@@ -590,7 +590,7 @@ void func_80C0217C(EnBomjimb* this, PlayState* play) {
 
     this->actor.world.rot.y = this->unk_2D6 + this->unk_2D4;
 
-    if (SurfaceType_GetSceneExitIndex(&play->colCtx, sp58, sp5C)) {
+    if (SurfaceType_GetSceneExitIndex(&play->colCtx, sp58, sp5C) != 0) {
         s16 temp = BINANG_SUB(this->actor.world.rot.y, this->actor.yawTowardsPlayer - 0x8000);
 
         if (temp < 0) {

src/overlays/actors/ovl_En_Horse/z_en_horse.c

@@ -4118,7 +4118,7 @@ s32 EnHorse_UpdateConveyors(EnHorse* this, PlayState* play) {
     }
 
     conveyorDir = SurfaceType_GetConveyorDirection(&play->colCtx, this->actor.floorPoly, this->actor.floorBgId);
-    conveyorDir = (conveyorDir * 0x400) - this->actor.world.rot.y;
+    conveyorDir = CONVEYOR_DIRECTION_TO_BINANG(conveyorDir) - this->actor.world.rot.y;
     if (conveyorDir > 0x640) {
         this->actor.world.rot.y += 0x640;
     } else if (conveyorDir < -0x640) {

src/overlays/actors/ovl_En_Test3/z_en_test3.c

@@ -950,7 +950,7 @@ s32 func_80A40230(EnTest3* this, PlayState* play) {
     dx = this->player.actor.world.pos.x - this->player.actor.prevPos.x;
     dy = this->player.actor.world.pos.z - this->player.actor.prevPos.z;
     this->player.linearVelocity = sqrtf(SQ(dx) + SQ(dy));
-    this->player.linearVelocity *= 1.0f + (1.05f * fabsf(Math_SinS(this->player.unk_B6C)));
+    this->player.linearVelocity *= 1.0f + (1.05f * fabsf(Math_SinS(this->player.floorPitch)));
     D_80A41D40 = (this->player.linearVelocity * 10.0f) + 20.0f;
     D_80A41D40 = CLAMP_MAX(D_80A41D40, 60.0f);
     D_80A41D44 = this->player.actor.world.rot.y;

tools/disasm/functions.txt

@@ -4419,13 +4419,13 @@
     0x80835428:("func_80835428",),
     0x808354A4:("func_808354A4",),
     0x808355D8:("func_808355D8",),
-    0x8083562C:("func_8083562C",),
+    0x8083562C:("Player_HandleExitsAndVoids",),
     0x80835BC8:("Player_TranslateAndRotateY",),
     0x80835BF8:("func_80835BF8",),
     0x80835C64:("Player_SpawnFairy",),
     0x80835CD8:("func_80835CD8",),
     0x80835D2C:("func_80835D2C",),
-    0x80835D58:("func_80835D58",),
+    0x80835D58:("Player_PosVsWallLineTest",),
     0x80835DF8:("func_80835DF8",),
     0x80835EAC:("Player_Door_Staircase",),
     0x8083604C:("Player_Door_Sliding",),
@@ -4532,7 +4532,7 @@
     0x8083CB58:("func_8083CB58",),
     0x8083CBC4:("func_8083CBC4",),
     0x8083CCB4:("func_8083CCB4",),
-    0x8083CF68:("func_8083CF68",),
+    0x8083CF68:("Player_HandleSlopes",),
     0x8083D168:("func_8083D168",),
     0x8083D23C:("func_8083D23C",),
     0x8083D6DC:("func_8083D6DC",),
@@ -4607,7 +4607,7 @@
     0x808425B4:("func_808425B4",),
     0x808426F0:("Player_SetDoAction",),
     0x808430E0:("func_808430E0",),
-    0x80843178:("func_80843178",),
+    0x80843178:("Player_ProcessSceneCollision",),
     0x80843EC0:("Player_UpdateCamAndSeqModes",),
     0x808442D8:("func_808442D8",),
     0x808445C4:("func_808445C4",),

tools/disasm/variables.txt

@@ -5013,7 +5013,7 @@
     0x8085D224:("D_8085D224","UNK_TYPE1","",0x30),
     0x8085D254:("D_8085D254","u16","[4]",0x8),
     0x8085D25C:("D_8085D25C","UNK_TYPE1","",0x1),
-    0x8085D264:("D_8085D264","UNK_TYPE1","",0x1),
+    0x8085D264:("sPlayerSlopeSlipAnims","UNK_TYPE1","",0x1),
     0x8085D26C:("D_8085D26C","UNK_TYPE1","",0x1),
     0x8085D270:("D_8085D270","UNK_TYPE1","",0x1),
     0x8085D27C:("D_8085D27C","Vec3f","",0xC),
@@ -5032,7 +5032,7 @@
     0x8085D340:("D_8085D340","UNK_TYPE1","",0x1),
     0x8085D34C:("D_8085D34C","UNK_TYPE1","",0x1),
     0x8085D354:("D_8085D354","UNK_TYPE1","",0x1),
-    0x8085D358:("D_8085D358","Vec3f","",0xC),
+    0x8085D358:("sInteractWallCheckOffset","Vec3f","",0xC),
     0x8085D364:("D_8085D364","UNK_TYPE1","",0x1),
     0x8085D370:("D_8085D370","UNK_TYPE1","",0x1),
     0x8085D37C:("D_8085D37C","UNK_TYPE1","",0x1),
@@ -5368,20 +5368,20 @@
     0x80862B00:("D_80862B00","UNK_TYPE1","",0x1),
     0x80862B02:("D_80862B02","UNK_TYPE1","",0x1),
     0x80862B04:("D_80862B04","UNK_TYPE1","",0x1),
-    0x80862B08:("sPlayerCurrentFloorType","UNK_TYPE1","",0x1),
-    0x80862B0C:("sPlayerCurrentWallFlags","UNK_TYPE1","",0x1),
+    0x80862B08:("sPlayerFloorType","UNK_TYPE1","",0x1),
+    0x80862B0C:("sPlayerTouchedWallFlags","UNK_TYPE1","",0x1),
     0x80862B10:("sPlayerConveyorSpeedIndex","UNK_TYPE1","",0x1),
     0x80862B14:("sPlayerIsOnFloorConveyor","UNK_TYPE1","",0x1),
-    0x80862B16:("D_80862B16","UNK_TYPE1","",0x1),
-    0x80862B18:("D_80862B18","f32","",0x4),
+    0x80862B16:("sPlayerConveyorYaw","UNK_TYPE1","",0x1),
+    0x80862B18:("sPlayerYDistToFloor","f32","",0x4),
     0x80862B1C:("sPlayerPrevFloorProperty","UNK_TYPE1","",0x1),
-    0x80862B20:("D_80862B20","UNK_TYPE1","",0x1),
-    0x80862B24:("D_80862B24","UNK_TYPE1","",0x1),
-    0x80862B28:("D_80862B28","UNK_TYPE1","",0x1),
+    0x80862B20:("sPlayerShapeYawToTouchedWall","UNK_TYPE1","",0x1),
+    0x80862B24:("sPlayerWorldYawToTouchedWall","UNK_TYPE1","",0x1),
+    0x80862B28:("sPlayerFloorPitchShape","UNK_TYPE1","",0x1),
     0x80862B2C:("D_80862B2C","UNK_TYPE1","",0x1),
-    0x80862B30:("D_80862B30","UNK_TYPE1","",0x1),
+    0x80862B30:("sPlayerInteractWallCheckResult","UNK_TYPE1","",0x1),
     0x80862B3C:("D_80862B3C","f32","",0x4),
-    0x80862B40:("D_80862B40","UNK_TYPE1","",0x1),
+    0x80862B40:("sPlayerFloorEffect","UNK_TYPE1","",0x1),
     0x80862B44:("sPlayerControlInput","UNK_TYPE1","",0x1),
     0x80862B48:("D_80862B48","UNK_TYPE1","",0x1),
     0x80862B4C:("D_80862B4C","UNK_TYPE1","",0x1),