Document versus rankings and finish info (#766)

* Document versus rankings and finish info

* Document race states

* variable renames

Author: JedGrabman

include/defines.h

@@ -529,3 +529,14 @@ player spins. Something  with avoding rollover of aniamation frame data? */
 #define FACING_Y_AXIS 0x4000
 #define FACING_X_AXIS 0x8000
 #define FACING_Z_AXIS 0x2000
+
+// race states
+
+#define RACE_NONE 0
+#define RACE_PREP 1
+#define RACE_STAGING 2
+#define RACE_IN_PROGRESS 3
+#define RACE_HUMAN_FINISHED 4 // At least 1 human has finished
+#define RACE_DONE 5
+#define RACE_QUITTING 6
+#define RACE_QUADRANT_RESULTS 7 // The results screen in GP and Time trials mode

src/code_800029B0.c

@@ -130,9 +130,9 @@ u16 D_8015F894;
 // Indexed by Player ID. Track time in seconds since player has last crossed the finish line
 f32 gTimePlayerLastTouchedFinishLine[8];
 
-u8* gNmiUnknown1;
-u8* gNmiUnknown2;
-u8* gNmiUnknown3;
+u8* nmi_gVersusResults2P;
+u8* nmi_gVersusResults3P;
+u8* nmi_gVersusResults4P;
 u8* gNmiUnknown4;
 u8* gNmiUnknown5;
 u8* gNmiUnknown6;
@@ -204,7 +204,7 @@ void setup_race(void) {
     func_80005310();
     func_8003D080();
     init_hud();
-    D_800DC510 = 0;
+    gRaceState = RACE_NONE;
     gNumSpawnedShells = 0;
     D_800DC5B8 = 0;
     D_80152308 = 0;

src/code_800029B0.h

@@ -118,9 +118,9 @@ extern u16 D_8015F892;
 extern u16 D_8015F894;
 extern f32 gTimePlayerLastTouchedFinishLine[];
 
-extern u8* gNmiUnknown1;
-extern u8* gNmiUnknown2;
-extern u8* gNmiUnknown3;
+extern u8* nmi_gVersusResults2P;
+extern u8* nmi_gVersusResults3P;
+extern u8* nmi_gVersusResults4P;
 extern u8* gNmiUnknown4;
 extern u8* gNmiUnknown5;
 extern u8* gNmiUnknown6;

src/cpu_vehicles_camera_path.c

@@ -88,7 +88,7 @@ u16 D_801631F8[10];
 f32 gCurrentCpuTargetSpeed;
 f32 gPreviousCpuTargetSpeed[10];
 s32 D_80163238;
-u16 D_80163240[12];
+u16 gCrossedFinishLine[12];
 u16 gWrongDirectionCounter[12];
 u16 gIsPlayerWrongDirection[12];
 s32 gPreviousLapProgressScore[10];
@@ -154,7 +154,7 @@ s16 D_80164358;
 s16 D_8016435A;
 s16 D_8016435C;
 s16 gGPCurrentRacePlayerIdByRank[12]; // D_80164360
-s16 D_80164378[12];
+s16 gPrevPlayerIdByRank[12];
 s32 gLapCountByPlayerId[10];          // D_80164390
 s32 gGPCurrentRaceRankByPlayerId[10]; // D_801643B8
 s32 gPreviousGPCurrentRaceRankByPlayerId[10];
@@ -707,15 +707,15 @@ void detect_wrong_player_direction(s32 playerId, Player* player) {
 }
 
 void set_places(void) {
-    s32 temp_s2;
-    f32 temp_f0;
-    s32 rankPlayer[8];
-    s32 a_really_cool_variable_name;
+    s32 playerIdToSwap;
+    f32 courseCompletionToSwap;
+    s32 playerIdByRank[8];
+    s32 prevPlayerId;
     UNUSED s32 pad;
     s32 numPlayer;
+    s32 rank;
     s32 playerId;
-    s32 temp_a0;
-    s32 var_t1_3;
+    s32 rankHigh;
 
     switch (gModeSelection) {
         case BATTLE:
@@ -731,69 +731,70 @@ void set_places(void) {
     }
 
     if (D_8016348C == 0) {
-        for (playerId = 0; playerId < numPlayer; playerId++) {
-            temp_a0 = gGPCurrentRacePlayerIdByRank[playerId];
-            rankPlayer[playerId] = temp_a0;
-            gCourseCompletionPercentByRank[playerId] = gCourseCompletionPercentByPlayerId[temp_a0];
+        for (rank = 0; rank < numPlayer; rank++) {
+            playerId = gGPCurrentRacePlayerIdByRank[rank];
+            playerIdByRank[rank] = playerId;
+            gCourseCompletionPercentByRank[rank] = gCourseCompletionPercentByPlayerId[playerId];
         }
     } else {
-        for (playerId = 0; playerId < numPlayer; playerId++) {
-            temp_a0 = gGPCurrentRacePlayerIdByRank[playerId];
-            rankPlayer[playerId] = temp_a0;
-            gCourseCompletionPercentByRank[playerId] = -gTimePlayerLastTouchedFinishLine[temp_a0];
+        // used in grand Prix mode once all players cross finish line to determine finish order
+        for (rank = 0; rank < numPlayer; rank++) {
+            playerId = gGPCurrentRacePlayerIdByRank[rank];
+            playerIdByRank[rank] = playerId;
+            gCourseCompletionPercentByRank[rank] = -gTimePlayerLastTouchedFinishLine[playerId];
         }
     }
 
-    for (playerId = 0; playerId < numPlayer - 1; playerId++) {
-        if ((gPlayers[gGPCurrentRacePlayerIdByRank[playerId]].type & PLAYER_CINEMATIC_MODE)) {
+    for (rank = 0; rank < numPlayer - 1; rank++) {
+        if ((gPlayers[gGPCurrentRacePlayerIdByRank[rank]].type & PLAYER_CINEMATIC_MODE)) {
             continue;
         }
 
-        for (var_t1_3 = playerId + 1; var_t1_3 < numPlayer; var_t1_3++) {
-            if (gCourseCompletionPercentByRank[playerId] < gCourseCompletionPercentByRank[var_t1_3]) {
-                if (!(gPlayers[gGPCurrentRacePlayerIdByRank[var_t1_3]].type & 0x800)) {
-                    temp_s2 = rankPlayer[playerId];
-                    rankPlayer[playerId] = rankPlayer[var_t1_3];
-                    rankPlayer[var_t1_3] = temp_s2;
-                    temp_f0 = gCourseCompletionPercentByRank[playerId];
-                    gCourseCompletionPercentByRank[playerId] = gCourseCompletionPercentByRank[var_t1_3];
-                    gCourseCompletionPercentByRank[var_t1_3] = temp_f0;
+        for (rankHigh = rank + 1; rankHigh < numPlayer; rankHigh++) {
+            if (gCourseCompletionPercentByRank[rank] < gCourseCompletionPercentByRank[rankHigh]) {
+                if (!(gPlayers[gGPCurrentRacePlayerIdByRank[rankHigh]].type & PLAYER_CINEMATIC_MODE)) {
+                    playerIdToSwap = playerIdByRank[rank];
+                    playerIdByRank[rank] = playerIdByRank[rankHigh];
+                    playerIdByRank[rankHigh] = playerIdToSwap;
+                    courseCompletionToSwap = gCourseCompletionPercentByRank[rank];
+                    gCourseCompletionPercentByRank[rank] = gCourseCompletionPercentByRank[rankHigh];
+                    gCourseCompletionPercentByRank[rankHigh] = courseCompletionToSwap;
                 }
             }
         }
     }
 
-    for (playerId = 0; playerId < NUM_PLAYERS; playerId++) {
-        gPreviousGPCurrentRaceRankByPlayerId[playerId] = gGPCurrentRaceRankByPlayerId[playerId];
+    // actually player_id, not rank
+    for (rank = 0; rank < NUM_PLAYERS; rank++) {
+        gPreviousGPCurrentRaceRankByPlayerId[rank] = gGPCurrentRaceRankByPlayerId[rank];
     }
 
-    for (playerId = 0; playerId < numPlayer; playerId++) {
-        gGPCurrentRacePlayerIdByRank[playerId] = rankPlayer[playerId];
-        gGPCurrentRaceRankByPlayerId[rankPlayer[playerId]] = playerId;
+    for (rank = 0; rank < numPlayer; rank++) {
+        gGPCurrentRacePlayerIdByRank[rank] = playerIdByRank[rank];
+        gGPCurrentRaceRankByPlayerId[playerIdByRank[rank]] = rank;
     }
-
-    for (playerId = 0; playerId < numPlayer; playerId++) {
-        a_really_cool_variable_name = D_80164378[playerId];
-        rankPlayer[playerId] = a_really_cool_variable_name;
-        gCourseCompletionPercentByRank[playerId] = gCourseCompletionPercentByPlayerId[a_really_cool_variable_name];
+    for (rank = 0; rank < numPlayer; rank++) {
+        prevPlayerId = gPrevPlayerIdByRank[rank];
+        playerIdByRank[rank] = prevPlayerId;
+        gCourseCompletionPercentByRank[rank] = gCourseCompletionPercentByPlayerId[prevPlayerId];
     }
 
-    for (playerId = 0; playerId < numPlayer - 1; playerId++) {
-        for (var_t1_3 = playerId + 1; var_t1_3 < numPlayer; var_t1_3++) {
-            if (gCourseCompletionPercentByRank[playerId] < gCourseCompletionPercentByRank[var_t1_3]) {
-                temp_s2 = rankPlayer[playerId];
-                rankPlayer[playerId] = rankPlayer[var_t1_3];
-                rankPlayer[var_t1_3] = temp_s2;
-                temp_f0 = gCourseCompletionPercentByRank[playerId];
-                gCourseCompletionPercentByRank[playerId] = gCourseCompletionPercentByRank[var_t1_3];
-                gCourseCompletionPercentByRank[var_t1_3] = temp_f0;
+    for (rank = 0; rank < numPlayer - 1; rank++) {
+        for (rankHigh = rank + 1; rankHigh < numPlayer; rankHigh++) {
+            if (gCourseCompletionPercentByRank[rank] < gCourseCompletionPercentByRank[rankHigh]) {
+                playerIdToSwap = playerIdByRank[rank];
+                playerIdByRank[rank] = playerIdByRank[rankHigh];
+                playerIdByRank[rankHigh] = playerIdToSwap;
+                courseCompletionToSwap = gCourseCompletionPercentByRank[rank];
+                gCourseCompletionPercentByRank[rank] = gCourseCompletionPercentByRank[rankHigh];
+                gCourseCompletionPercentByRank[rankHigh] = courseCompletionToSwap;
             }
         }
     }
 
-    for (playerId = 0; playerId < numPlayer; playerId++) {
-        gGPCurrentRaceRankByPlayerIdDup[rankPlayer[playerId]] = playerId;
-        D_80164378[playerId] = rankPlayer[playerId];
+    for (rank = 0; rank < numPlayer; rank++) {
+        gGPCurrentRaceRankByPlayerIdDup[playerIdByRank[rank]] = rank;
+        gPrevPlayerIdByRank[rank] = playerIdByRank[rank];
     }
 }
 
@@ -992,7 +993,7 @@ bool func_800088D8(s32 playerId, s16 arg1, s16 arg2) {
     if (arg2 == 0) {
         if (gDemoMode == 1) {
             STEMP_V0 = gNumPathPointsTraversed[playerId];
-            STEMP_V1 = gNumPathPointsTraversed[D_80164378[7]];
+            STEMP_V1 = gNumPathPointsTraversed[gPrevPlayerIdByRank[7]];
             progress = STEMP_V0 - STEMP_V1;
             if (progress < 0) {
                 progress = -progress;
@@ -1018,7 +1019,7 @@ bool func_800088D8(s32 playerId, s16 arg1, s16 arg2) {
         rank = gGPCurrentRaceRankByPlayerId[gBestRankedHumanPlayer];
         if (((((gPathCountByPathIndex[0] * 2) / 3)) < progress) && ((rank) >= 6)) {
             STEMP_V0 = gNumPathPointsTraversed[playerId];
-            STEMP_V1 = temp = gNumPathPointsTraversed[D_80164378[rank - 1]];
+            STEMP_V1 = temp = gNumPathPointsTraversed[gPrevPlayerIdByRank[rank - 1]];
             progress = STEMP_V0 - STEMP_V1;
         }
         if (progress < 0) {
@@ -1200,11 +1201,12 @@ void update_cpu_path_completion(s32 playerId, Player* player) {
 
 /**
  * Helps calculate time since player last touched finishline.
+ * Assumes constant z-speed and subtracts portion of frame where the finish line was already crossed
  **/
-f32 func_80009258(UNUSED s32 playerId, f32 arg1, f32 arg2) {
-    f32 temp_f2 = gPathStartZ - arg2;
-    f32 temp_f12 = arg1 - gPathStartZ;
-    return gCourseTimer - ((COURSE_TIMER_ITER_f * temp_f2) / (temp_f2 + temp_f12));
+f32 time_crossed_finish_line(UNUSED s32 playerId, f32 previousPlayerZ, f32 playerZ) {
+    f32 z_change_after_cross = gPathStartZ - playerZ;
+    f32 z_change_before_cross = previousPlayerZ - gPathStartZ;
+    return gCourseTimer - ((COURSE_TIMER_ITER_f * z_change_after_cross) / (z_change_after_cross + z_change_before_cross));
 }
 
 void update_player_path_completion(s32 playerId, Player* player) {
@@ -1220,7 +1222,7 @@ void update_player_path_completion(s32 playerId, Player* player) {
     playerZ = player->pos[2];
     previousPlayerZ = gPreviousPlayerZ[playerId];
     gIsPlayerNewPathPoint = false;
-    D_80163240[playerId] = 0;
+    gCrossedFinishLine[playerId] = 0;
     sSomeNearestPathPoint = update_player_path(playerX, playerY, playerZ, gNearestPathPointByPlayerId[playerId], player,
                                                playerId, gPlayerPathIndex);
     gCurrentNearestPathPoint = sSomeNearestPathPoint;
@@ -1276,12 +1278,12 @@ void update_player_path_completion(s32 playerId, Player* player) {
                         // clang-format on
                     }
                 }
-                D_80163240[playerId] = 1;
+                gCrossedFinishLine[playerId] = 1;
                 update_player_completion(playerId);
                 reset_cpu_behaviour(playerId);
                 cpu_ItemStrategy[playerId].numItemUse = 0;
                 if ((D_8016348C == 0) && !(player->type & PLAYER_CINEMATIC_MODE)) {
-                    gTimePlayerLastTouchedFinishLine[playerId] = func_80009258(playerId, previousPlayerZ, playerZ);
+                    gTimePlayerLastTouchedFinishLine[playerId] = time_crossed_finish_line(playerId, previousPlayerZ, playerZ);
                 }
             }
         }
@@ -1461,7 +1463,11 @@ void update_player(s32 playerId) {
                 player->kartProps &= ~BACK_UP;
             }
             update_player_path_completion(playerId, player);
-            if ((gCurrentCourseId != COURSE_AWARD_CEREMONY) && ((D_80163240[playerId] == 1) || (playerId == 0))) {
+
+            // Because this takes place in a per-player loop and runs primarily when player 1 crosses the finish line,
+            // player 1 effectively has a 1 frame advantage when determining places. However, it runs for everyone when
+            // they cross the finish line, resulting in lower port numbers always winning ties in versus mode.
+            if ((gCurrentCourseId != COURSE_AWARD_CEREMONY) && ((gCrossedFinishLine[playerId] == 1) || (playerId == 0))) {
                 set_places();
             }
             if (player->type & PLAYER_CPU) {
@@ -2100,7 +2106,7 @@ void init_players(void) {
         }
         temp_v0_3 = gGPCurrentRaceRankByPlayerId[i];
         gGPCurrentRacePlayerIdByRank[temp_v0_3] = (s16) i;
-        D_80164378[temp_v0_3] = (s16) i;
+        gPrevPlayerIdByRank[temp_v0_3] = (s16) i;
         gGPCurrentRaceRankByPlayerIdDup[i] = temp_v0_3;
         gWrongDirectionCounter[i] = 0;
         gIsPlayerWrongDirection[i] = 0;

src/cpu_vehicles_camera_path.h

@@ -115,7 +115,7 @@ void update_player_completion(s32);
 
 void yoshi_valley_cpu_path(s32);
 void update_cpu_path_completion(s32, Player*);
-f32 func_80009258(s32, f32, f32);
+f32 time_crossed_finish_line(s32, f32, f32);
 void update_player_path_completion(s32, Player*);
 void update_vehicles(void);
 void play_cpu_sound_effect(s32, Player*);
@@ -323,7 +323,7 @@ extern u16 D_801631F8[];
 extern f32 gCurrentCpuTargetSpeed;
 extern f32 gPreviousCpuTargetSpeed[];
 extern s32 D_80163238;
-extern u16 D_80163240[];
+extern u16 gCrossedFinishLine[];
 extern u16 gWrongDirectionCounter[];
 extern u16 gIsPlayerWrongDirection[];
 extern s32 gPreviousLapProgressScore[];
@@ -383,7 +383,7 @@ extern s16 D_80164358;
 extern s16 D_8016435A;
 extern s16 D_8016435C;
 extern s16 gGPCurrentRacePlayerIdByRank[]; // D_80164360
-extern s16 D_80164378[];
+extern s16 gPrevPlayerIdByRank[];          // D_80164378
 extern s32 gLapCountByPlayerId[];          // D_80164390
 extern s32 gGPCurrentRaceRankByPlayerId[]; // D_801643B8
 extern s32 gPreviousGPCurrentRaceRankByPlayerId[];

src/main.c

@@ -1,5 +1,5 @@
 #ifndef GCC
-#define D_800DC510_AS_U16
+#define gRaceState_AS_U16
 #endif
 #include <ultra64.h>
 #include <PR/os.h>
@@ -162,8 +162,8 @@ OSMesg gPIMesgBuf[32];
 OSMesgQueue gPIMesgQueue;
 
 s32 gGamestate = 0xFFFF;
-// D_800DC510 is externed as an s32 in other files. D_800DC514 is only used in main.c, likely a developer mistake.
-u16 D_800DC510 = 0;
+// gRaceState is externed as an s32 in other files. D_800DC514 is only used in main.c, likely a developer mistake.
+u16 gRaceState = RACE_NONE;
 u16 D_800DC514 = 0;
 u16 creditsRenderMode = 0; // Renders the whole track. Displays red if used in normal race mode.
 u16 gDemoMode = DEMO_MODE_INACTIVE;
@@ -1179,10 +1179,10 @@ void thread5_game_loop(UNUSED void* arg) {
     set_vblank_handler(2, &gGameVblankHandler, &gGameVblankQueue, (OSMesg) OS_EVENT_SW2);
     // These variables track stats such as player wins.
     // In the event of a console reset, it remembers them.
-    gNmiUnknown1 = &pAppNmiBuffer[0]; // 2  u8's, tracks number of times player 1/2 won a VS race
-    gNmiUnknown2 =
+    nmi_gVersusResults2P = &pAppNmiBuffer[0]; // 2  u8's, tracks number of times player 1/2 won a VS race
+    nmi_gVersusResults3P =
         &pAppNmiBuffer[2]; // 9  u8's, 3x3, tracks number of times player 1/2/3   has placed in 1st/2nd/3rd in a VS race
-    gNmiUnknown3 = &pAppNmiBuffer[11]; // 12 u8's, 4x3, tracks number of times player 1/2/3/4 has placed in 1st/2nd/3rd
+    nmi_gVersusResults4P = &pAppNmiBuffer[11]; // 12 u8's, 4x3, tracks number of times player 1/2/3/4 has placed in 1st/2nd/3rd
                                        // in a VS race
     gNmiUnknown4 = &pAppNmiBuffer[23]; // 2  u8's, tracking number of Battle mode wins by player 1/2
     gNmiUnknown5 = &pAppNmiBuffer[25]; // 3  u8's, tracking number of Battle mode wins by player 1/2/3

src/main.h

@@ -198,13 +198,13 @@ extern OSMesg gPIMesgBuf[];
 extern OSMesgQueue gPIMesgQueue;
 void race_logic_loop(void);
 extern s32 gGamestate;
-#ifndef D_800DC510_AS_U16
+#ifndef gRaceState_AS_U16
 // Prevent overlapping writes in gcc
-// Whether D_800DC510 was intended to be a separate variable in main.c from the rest of the game is unknown
+// Whether gRaceState was intended to be a separate variable in main.c from the rest of the game is unknown
 #ifdef GCC
-extern u16 D_800DC510;
+extern u16 gRaceState;
 #else
-extern s32 D_800DC510;
+extern s32 gRaceState;
 #endif
 #endif