Document z_horse.c and related actors (#2278)

* document z_horse.h

* .bss

* suggestions and more comments

* bss

* INGORACE -> INGO_RACE

* format header macros

* FIx incorrect type comparision

* EnInMode -> EnInStartMode

* R_EXITED_SCENE_RIDING_HORSE

5 files changed, 65 insertions, 56 deletions

diff --git a/include/functions.h b/include/functions.h
index 0a4c8004c..7a114f73c 100644
--- a/include/functions.h
+++ b/include/functions.h
@@ -71,13 +71,6 @@ void CutsceneFlags_UnsetAll(PlayState* play);
 void CutsceneFlags_Set(PlayState* play, s16 flag);
 void CutsceneFlags_Unset(PlayState* play, s16 flag);
 s32 CutsceneFlags_Get(PlayState* play, s16 flag);
-s32 func_8006CFC0(s32 sceneId);
-void func_8006D074(PlayState* play);
-void func_8006D0AC(PlayState* play);
-void func_8006D0EC(PlayState* play, Player* player);
-void func_8006D684(PlayState* play, Player* player);
-void func_8006DC68(PlayState* play, Player* player);
-void func_8006DD9C(Actor* actor, Vec3f* arg1, s16 arg2);
 
 s32 Kanji_OffsetFromShiftJIS(s32 character);
 void Font_LoadCharWide(Font* font, u16 character, u16 codePointIndex);
diff --git a/include/regs.h b/include/regs.h
index 335861f25..50e43769c 100644
--- a/include/regs.h
+++ b/include/regs.h
@@ -118,6 +118,8 @@
 #define R_MESSAGE_DEBUGGER_TEXTID                YREG(79)
 #define R_C_UP_ICON_X                            YREG(88)
 #define R_C_UP_ICON_Y                            YREG(89)
+#define R_EXITED_SCENE_RIDING_HORSE              AREG(6) // Used to spawn the player on top of Epona in the next scene
+#define R_DEBUG_FORCE_EPONA_OBTAINED             DREG(1) // If set, overrides EVENTCHKINF_EPONA_OBTAINED state giving Epona
 #define R_EPONAS_SONG_PLAYED                     DREG(53)
 #define R_MAGIC_FILL_COLOR(i)                    ZREG(0 + (i))
 #define R_PAUSE_PAGE_SWITCH_FRAME_ADVANCE_ON     ZREG(13)
diff --git a/include/z64actor.h b/include/z64actor.h
index 40b772cee..6df270345 100644
--- a/include/z64actor.h
+++ b/include/z64actor.h
@@ -838,10 +838,10 @@ int func_8002DD78(struct Player* player);
 s32 func_8002DDE4(struct PlayState* play);
 s32 func_8002DDF4(struct PlayState* play);
 void Actor_SwapHookshotAttachment(struct PlayState* play, Actor* srcActor, Actor* destActor);
-void func_8002DE74(struct PlayState* play, struct Player* player);
+void Actor_RequestHorseCameraSetting(struct PlayState* play, struct Player* player);
 void Actor_MountHorse(struct PlayState* play, struct Player* player, Actor* horse);
 int func_8002DEEC(struct Player* player);
-void func_8002DF18(struct PlayState* play, struct Player* player);
+void Actor_InitPlayerHorse(struct PlayState* play, struct Player* player);
 s32 Player_SetCsAction(struct PlayState* play, Actor* csActor, u8 csAction);
 s32 Player_SetCsActionWithHaltedActors(struct PlayState* play, Actor* csActor, u8 csAction);
 void func_8002DF90(DynaPolyActor* dynaActor);
diff --git a/include/z64horse.h b/include/z64horse.h
new file mode 100644
index 000000000..d58de4b6d
--- /dev/null
+++ b/include/z64horse.h
@@ -0,0 +1,16 @@
+#ifndef Z64HORSE_H
+#define Z64HORSE_H
+
+#include "ultra64.h"
+#include "z64math.h"
+
+struct PlayState;
+struct Actor;
+struct Player;
+
+void Horse_ResetHorseData(struct PlayState* play);
+void Horse_FixLakeHyliaPosition(struct PlayState* play);
+void Horse_InitPlayerHorse(struct PlayState* play, struct Player* player);
+void Horse_RotateToPoint(struct Actor* actor, Vec3f* pos, s16 turnAmount);
+
+#endif
diff --git a/include/z64save.h b/include/z64save.h
index 856514141..68f6028ca 100644
--- a/include/z64save.h
+++ b/include/z64save.h
@@ -893,66 +893,65 @@ typedef enum LinkAge {
  * SaveContext.eventInf
  */
 
-// 0x00-0x0F
-// horses related
+// EVENTINF 0x00-0x0F
+// Ingo Race, Lon Lon Ranch minigames, and Horseback Archery minigame flags
 #define EVENTINF_HORSES_INDEX 0
-#define EVENTINF_HORSES_STATE_SHIFT 0
-#define EVENTINF_HORSES_HORSETYPE_SHIFT 4
-#define EVENTINF_HORSES_05_SHIFT 5
-#define EVENTINF_HORSES_06_SHIFT 6
-#define EVENTINF_HORSES_08_SHIFT 8
-#define EVENTINF_HORSES_0A_SHIFT 10
-#define EVENTINF_HORSES_0F_SHIFT 15 // unused?
-#define EVENTINF_HORSES_STATE_MASK (0xF << EVENTINF_HORSES_STATE_SHIFT)
-#define EVENTINF_HORSES_HORSETYPE_MASK (1 << EVENTINF_HORSES_HORSETYPE_SHIFT)
-#define EVENTINF_HORSES_05_MASK (1 << EVENTINF_HORSES_05_SHIFT)
-#define EVENTINF_HORSES_06_MASK (1 << EVENTINF_HORSES_06_SHIFT)
-#define EVENTINF_HORSES_0F_MASK (1 << EVENTINF_HORSES_0F_SHIFT)
-#define EVENTINF_HORSES_05 ((EVENTINF_HORSES_INDEX << 4) | EVENTINF_HORSES_05_SHIFT)
-#define EVENTINF_HORSES_06 ((EVENTINF_HORSES_INDEX << 4) | EVENTINF_HORSES_06_SHIFT)
+// EVENTINF 0x00-0x03 reserved for IngoRaceState
+#define EVENTINF_INGO_RACE_STATE_MASK (0xF << 0)
+typedef enum IngoRaceState {
+    /* 0 */ INGO_RACE_STATE_OFFER_RENTAL,
+    /* 1 */ INGO_RACE_STATE_HORSE_RENTAL_PERIOD,
+    /* 2 */ INGO_RACE_STATE_RACING,
+    /* 3 */ INGO_RACE_STATE_PLAYER_LOSE,
+    /* 4 */ INGO_RACE_STATE_FIRST_WIN,
+    /* 5 */ INGO_RACE_STATE_TRAPPED_WIN_UNUSED,
+    /* 6 */ INGO_RACE_STATE_TRAPPED_WIN_EPONA, // Ingo Traps you in Lon Lon
+    /* 7 */ INGO_RACE_STATE_REMATCH
+} IngoRaceState;
+
+#define EVENTINF_INGO_RACE_HORSETYPE 4
+#define EVENTINF_INGO_RACE_HORSETYPE_MASK (1 << EVENTINF_INGO_RACE_HORSETYPE)
+#define EVENTINF_INGO_RACE_LOST_ONCE 5
+#define EVENTINF_INGO_RACE_LOST_ONCE_MASK (1 << EVENTINF_INGO_RACE_LOST_ONCE)
+#define EVENTINF_INGO_RACE_SECOND_RACE 6
+#define EVENTINF_INGO_RACE_SECOND_RACE_MASK (1 << EVENTINF_INGO_RACE_SECOND_RACE)
 // Used in z_en_ta (Talon) to store Cucco game winning status
 // and in z_en_ge1 (Gerudo) to store archery in-progress status
-#define EVENTINF_HORSES_08 ((EVENTINF_HORSES_INDEX << 4) | EVENTINF_HORSES_08_SHIFT)
+#define EVENTINF_HORSES_08 8
 #define EVENTINF_CUCCO_GAME_WON EVENTINF_HORSES_08
 // Used in z_en_ta (Talon) and z_en_ma3 (Malon) to store minigame finishing status
-#define EVENTINF_HORSES_0A ((EVENTINF_HORSES_INDEX << 4) | EVENTINF_HORSES_0A_SHIFT)
+#define EVENTINF_HORSES_0A 10
 #define EVENTINF_CUCCO_GAME_FINISHED EVENTINF_HORSES_0A
-
-typedef enum EventInfHorsesState {
-    /* 0 */ EVENTINF_HORSES_STATE_0,
-    /* 1 */ EVENTINF_HORSES_STATE_1,
-    /* 2 */ EVENTINF_HORSES_STATE_2,
-    /* 3 */ EVENTINF_HORSES_STATE_3,
-    /* 4 */ EVENTINF_HORSES_STATE_4,
-    /* 5 */ EVENTINF_HORSES_STATE_5,
-    /* 6 */ EVENTINF_HORSES_STATE_6,
-    /* 7 */ EVENTINF_HORSES_STATE_7
-} EventInfHorsesState;
+#define EVENTINF_INGO_RACE_0F 15 // unused?
+#define EVENTINF_INGO_RACE_0F_MASK (1 << EVENTINF_INGO_RACE_0F)
 
 // "InRaceSeq"
-#define GET_EVENTINF_HORSES_STATE() \
-    ((gSaveContext.eventInf[EVENTINF_HORSES_INDEX] & EVENTINF_HORSES_STATE_MASK) >> EVENTINF_HORSES_STATE_SHIFT)
-#define SET_EVENTINF_HORSES_STATE(v)                                                   \
-    gSaveContext.eventInf[EVENTINF_HORSES_INDEX] =                                     \
-        (gSaveContext.eventInf[EVENTINF_HORSES_INDEX] & ~EVENTINF_HORSES_STATE_MASK) | \
-        ((v) << EVENTINF_HORSES_STATE_SHIFT)
-
-#define GET_EVENTINF_HORSES_HORSETYPE() \
-    ((gSaveContext.eventInf[EVENTINF_HORSES_INDEX] & EVENTINF_HORSES_HORSETYPE_MASK) >> EVENTINF_HORSES_HORSETYPE_SHIFT)
-#define SET_EVENTINF_HORSES_HORSETYPE(v)                                                   \
-    gSaveContext.eventInf[EVENTINF_HORSES_INDEX] =                                         \
-        (gSaveContext.eventInf[EVENTINF_HORSES_INDEX] & ~EVENTINF_HORSES_HORSETYPE_MASK) | \
-        ((v) << EVENTINF_HORSES_HORSETYPE_SHIFT)
-
-#define SET_EVENTINF_HORSES_0F(v)                  \
+#define GET_EVENTINF_INGO_RACE_STATE() (gSaveContext.eventInf[EVENTINF_HORSES_INDEX] & EVENTINF_INGO_RACE_STATE_MASK)
+
+#define SET_EVENTINF_INGO_RACE_STATE(v)            \
     gSaveContext.eventInf[EVENTINF_HORSES_INDEX] = \
-        (gSaveContext.eventInf[EVENTINF_HORSES_INDEX] & ~EVENTINF_HORSES_0F_MASK) | ((v) << EVENTINF_HORSES_0F_SHIFT)
+        (gSaveContext.eventInf[EVENTINF_HORSES_INDEX] & ~EVENTINF_INGO_RACE_STATE_MASK) | (v)
 
+#define GET_EVENTINF_INGO_RACE_FLAG(flag) \
+    ((gSaveContext.eventInf[EVENTINF_HORSES_INDEX] & (1 << ((flag) & 0xF))) >> ((flag) & 0xF))
+
+#define SET_EVENTINF_INGO_RACE_FLAG(flag)          \
+    gSaveContext.eventInf[EVENTINF_HORSES_INDEX] = \
+        (gSaveContext.eventInf[EVENTINF_HORSES_INDEX] & 0xFFFF) | (1 << ((flag) & 0xF))
+
+#define WRITE_EVENTINF_INGO_RACE_FLAG(flag, v)     \
+    gSaveContext.eventInf[EVENTINF_HORSES_INDEX] = \
+        (gSaveContext.eventInf[EVENTINF_HORSES_INDEX] & ~(1 << ((flag) & 0xF))) | ((v) << ((flag) & 0xF))
+
+#define GET_EVENTINF_INGO_RACE_HORSETYPE() GET_EVENTINF_INGO_RACE_FLAG(EVENTINF_INGO_RACE_HORSETYPE)
+#define WRITE_EVENTINF_INGO_RACE_HORSETYPE(v) WRITE_EVENTINF_INGO_RACE_FLAG(EVENTINF_INGO_RACE_HORSETYPE, v)
+
+#define WRITE_EVENTINF_INGO_RACE_0F(v) WRITE_EVENTINF_INGO_RACE_FLAG(EVENTINF_INGO_RACE_0F, v)
 
 // Is the running man race active
 #define EVENTINF_MARATHON_ACTIVE 0x10
 
-// 0x20-0x24
+// EVENTINF 0x20-0x24
 #define EVENTINF_20_21_22_23_24_INDEX 2
 #define EVENTINF_20_MASK (1 << 0)
 #define EVENTINF_21_MASK (1 << 1)
@@ -962,7 +961,6 @@ typedef enum EventInfHorsesState {
 
 #define EVENTINF_30 0x30
 
-
 #define GET_EVENTINF(flag) (gSaveContext.eventInf[(flag) >> 4] & (1 << ((flag) & 0xF)))
 #define SET_EVENTINF(flag) (gSaveContext.eventInf[(flag) >> 4] |= (1 << ((flag) & 0xF)))
 #define CLEAR_EVENTINF(flag) (gSaveContext.eventInf[(flag) >> 4] &= ~(1 << ((flag) & 0xF)))