EnBaba Documented (Bomb Shop Lady) (#825)

* Merge in sub_s_models

* Update subs DL names

* Unused Weight pathing

* Function headers for weightpathing

* TimePathing WIP

* Timepathing, still unsure about unk184

* Move subs functions from functions.h to z64subs.h

* Add fake comment

* Some cleanup and renames

* Renames/cleanup of actors that use timepath

* Cleanup

* More cleanup

* Rename unk stuff

* Merge in upstream/master

* TimeElapsed -> elapsedTime

* Fix

* Final cleanup

* SubS Time Paths

* Still needs dialog action functions

* Fix waypoint comments

* Review pt. 1

* Baba review

* ScheduleResult -> ScheduleOutput

* Forgot to update functions.txt oops

* Add clarifying comment to SubS_TimePathing_FillWeightArray

* format.sh

* Finish up docs

* Fix order comments

* Fix

* Change bombShopkeeper struct member to

* Fix a few merge mistakes

* Add ScheduleOutput to namefixer

* format

* Format and fix merge

* Review

* PR

* z64schedule.h

* text summary

Co-authored-by: Maide <34639600+Kelebek1@users.noreply.github.com>
Co-authored-by: Tom Overton <tom-overton@users.noreply.github.com>

3 files changed, 36 insertions, 28 deletions

diff --git a/include/functions.h b/include/functions.h
index 63f9eadd8..257276806 100644
--- a/include/functions.h
+++ b/include/functions.h
@@ -2247,7 +2247,7 @@ s32 Entrance_GetSceneNum(u16 entranceIndex);
 s32 Entrance_GetSceneNumAbsolute(u16 entranceIndex);
 s32 Entrance_GetSpawnNum(u16 entranceIndex);
 s32 Entrance_GetTransitionFlags(u16 entranceIndex);
-s32 Schedule_RunScript(PlayState* play, u8* script, ScheduleResult* result);
+s32 Schedule_RunScript(PlayState* play, u8* script, ScheduleOutput* output);
 void SkelAnime_DrawLimbLod(PlayState* play, s32 limbIndex, void** skeleton, Vec3s* jointTable, OverrideLimbDrawOpa overrideLimbDraw, PostLimbDrawOpa postLimbDraw, Actor* actor, s32 lod);
 void SkelAnime_DrawLod(PlayState* play, void** skeleton, Vec3s* jointTable, OverrideLimbDrawOpa overrideLimbDraw, PostLimbDrawOpa postLimbDraw, Actor* actor, s32 lod);
 void SkelAnime_DrawFlexLimbLod(PlayState* play, s32 limbIndex, void** skeleton, Vec3s* jointTable, OverrideLimbDrawFlex overrideLimbDraw, PostLimbDrawFlex postLimbDraw, Actor* actor, s32 lod, Mtx** mtx);
diff --git a/include/z64schedule.h b/include/z64schedule.h
index f5dfb2be8..6a0a32638 100644
--- a/include/z64schedule.h
+++ b/include/z64schedule.h
@@ -3,37 +3,45 @@
 
 #include "ultra64.h"
 
-/*
-  Schedule is a subsystem that acts as a way to make decisions based on the
-  time and scene (and a limited selection of items). It is utilized by writing
-  a script that is encoded into bytecode and ran, returning the result in a
-  struct. The returned result can be a value or a encoded time value.
-
-  The scripts contain 2 kinds of instructions:
-  - Checks with branches (relative offsets, either 1-byte offsets (short, *_S),
-                          or 2-byte offsets (long, *_L))
-  - Returns
-
-  Scripts are stored as u8[]. They are built using the macros are the bottom of
-  this file. The scheduledis.py script can be used to convert any scripts in
-  actor data into the macros.
-*/
+/**
+ *   Schedule is a subsystem that acts as a way to make decisions based on the
+ * time and scene (and a limited selection of items). It is utilized by writing
+ * a script that is encoded into bytecode and ran, returning the result in a
+ * struct. The returned result can be a value or a encoded time value.
+ *
+ * The scripts contain 2 kinds of instructions:
+ * - Checks with branches (relative offsets, either 1-byte offsets (short, *_S),
+ *                         or 2-byte offsets (long, *_L))
+ * - Returns
+ *
+ * Scripts are stored as u8[]. They are built using the macros are the bottom of
+ * this file. The scheduledis.py script can be used to convert any scripts in
+ * actor data into the macros.
+ */
+
+/**
+ * Actors that use this system generally create 3 functions to interact with it.
+ *
+ * - FollowSchedule: The action function an actor sets to follow the schedule.
+ * - ProcessScheduleOutput: Holds the logic of processing the output received by running the schedule script, called by FollowSchedule
+ * - HandleSchedule: Holds the actual logic of how to actually follow the schedule based on the processed output, called by FollowSchedule
+ */
 
 // Macro to convert the time format used in the save struct into the format used in Schedule
 #define SCHEDULE_CONVERT_TIME(time) ((time) - 0x10000 / 360 * 90)
 #define SCHEDULE_TIME_NOW SCHEDULE_CONVERT_TIME(gSaveContext.save.time)
 
 typedef enum {
-    /* 00 */ SCHEDULE_CMD_ID_CHECK_FLAG_S,         // Checks if a weekEventReg flag is set and branches if so, short range branch
-    /* 01 */ SCHEDULE_CMD_ID_CHECK_FLAG_L,         // Checks if a weekEventReg flag is set and branches if so, long range branch
-    /* 02 */ SCHEDULE_CMD_ID_CHECK_TIME_RANGE_S,   // Checks if the current time is within the range of the two provided times and branches if so, short range branch
-    /* 03 */ SCHEDULE_CMD_ID_CHECK_TIME_RANGE_L,   // Checks if the current time is within the range of the two provided times and branches if so, long range branch
-    /* 04 */ SCHEDULE_CMD_ID_RET_VAL_L,            // Ends script and returns 2-byte value (Note: bugged as the return value size is only 1 byte in the struct)
-    /* 05 */ SCHEDULE_CMD_ID_RET_NONE,             // Ends script without returning anything
-    /* 06 */ SCHEDULE_CMD_ID_RET_EMPTY,            // Ends script and indicates return without changing existing value
-    /* 07 */ SCHEDULE_CMD_ID_NOP,                  // No-Op
-    /* 08 */ SCHEDULE_CMD_ID_CHECK_MISC_S,         // Special check based on items or masks and branches if check passes, short range branch
-    /* 09 */ SCHEDULE_CMD_ID_RET_VAL_S,            // Ends script and returns byte value
+    /*  0 */ SCHEDULE_CMD_ID_CHECK_FLAG_S,         // Checks if a weekEventReg flag is set and branches if so, short range branch
+    /*  1 */ SCHEDULE_CMD_ID_CHECK_FLAG_L,         // Checks if a weekEventReg flag is set and branches if so, long range branch
+    /*  2 */ SCHEDULE_CMD_ID_CHECK_TIME_RANGE_S,   // Checks if the current time is within the range of the two provided times and branches if so, short range branch
+    /*  3 */ SCHEDULE_CMD_ID_CHECK_TIME_RANGE_L,   // Checks if the current time is within the range of the two provided times and branches if so, long range branch
+    /*  4 */ SCHEDULE_CMD_ID_RET_VAL_L,            // Ends script and returns 2-byte value (Note: bugged as the return value size is only 1 byte in the struct)
+    /*  5 */ SCHEDULE_CMD_ID_RET_NONE,             // Ends script without returning anything
+    /*  6 */ SCHEDULE_CMD_ID_RET_EMPTY,            // Ends script and indicates return without changing existing value
+    /*  7 */ SCHEDULE_CMD_ID_NOP,                  // No-Op
+    /*  8 */ SCHEDULE_CMD_ID_CHECK_MISC_S,         // Special check based on items or masks and branches if check passes, short range branch
+    /*  9 */ SCHEDULE_CMD_ID_RET_VAL_S,            // Ends script and returns byte value
     /* 10 */ SCHEDULE_CMD_ID_CHECK_NOT_IN_SCENE_S, // Checks if the current scene is not SceneNum and branches if so, short range branch
     /* 11 */ SCHEDULE_CMD_ID_CHECK_NOT_IN_SCENE_L, // Checks if the current scene is not SceneNum and branches if so, long range branch
     /* 12 */ SCHEDULE_CMD_ID_CHECK_NOT_IN_DAY_S,   // Checks if the current day is not Day and branches if so, short range branch
@@ -56,7 +64,7 @@ typedef struct {
     /* 0x4 */ s32 time0;
     /* 0x8 */ s32 time1;
     /* 0xC */ s32 hasResult;
-} ScheduleResult; // size = 0x10
+} ScheduleOutput; // size = 0x10
 
 typedef struct {
     /* 0x0 */ u8 cmd;
diff --git a/include/z64subs.h b/include/z64subs.h
index 60c3e7151..ff9404e9d 100644
--- a/include/z64subs.h
+++ b/include/z64subs.h
@@ -122,7 +122,7 @@ void SubS_GenShadowTex(Vec3f bodyPartsPos[], Vec3f* worldPos, u8* tex, f32 tween
 void SubS_DrawShadowTex(Actor* actor, struct GameState* gameState, u8* tex);
 
 s16 SubS_ComputeTrackPointRot(s16* rot, s16 rotMax, s16 target, f32 slowness, f32 stepMin, f32 stepMax);
-s32 SubS_TrackPoint(Vec3f* point, Vec3f* focusPos, Vec3s* shapeRot, Vec3s* turnTarget, Vec3s* headRot, Vec3s* torsoRot, TrackOptionsSet* options);
+s32 SubS_TrackPoint(Vec3f* point, Vec3f* focusPos, Vec3s* shapeRot, Vec3s* trackTarget, Vec3s* headRot, Vec3s* torsoRot, TrackOptionsSet* options);
 
 s32 SubS_AngleDiffLessEqual(s16 angleA, s16 threshold, s16 angleB);