Document Update Actor Flags (#1762)

* name flags, TODO: comments

* comments

* improve comments

* small cleanup

* cleanup comment

5 files changed, 23 insertions, 22 deletions

diff --git a/src/code/z_actor.c b/src/code/z_actor.c
index d9ced77fa..9b1d38d0e 100644
--- a/src/code/z_actor.c
+++ b/src/code/z_actor.c
@@ -2556,9 +2556,8 @@ typedef struct {
     /* 0x0C */ u32 canFreezeCategory;
     /* 0x10 */ Actor* talkActor;
     /* 0x14 */ Player* player;
-    /* 0x18 */ u32 unk_18; // Bitmask of actor flags. The actor will only have main called if it has at least 1
-                           // flag set that matches this bitmask
-} UpdateActor_Params;      // size = 0x1C
+    /* 0x18 */ u32 updateActorFlagsMask; // Actor will update only if at least 1 actor flag is set in this bitmask
+} UpdateActor_Params;                    // size = 0x1C
 
 Actor* Actor_UpdateActor(UpdateActor_Params* params) {
     PlayState* play = params->play;
@@ -2591,7 +2590,7 @@ Actor* Actor_UpdateActor(UpdateActor_Params* params) {
             Actor_Kill(actor);
         } else if (((params->freezeExceptionFlag != 0) && !(actor->flags & params->freezeExceptionFlag)) ||
                    (((!params->freezeExceptionFlag) != 0) &&
-                    (!(actor->flags & ACTOR_FLAG_100000) ||
+                    (!(actor->flags & ACTOR_FLAG_FREEZE_EXCEPTION) ||
                      ((actor->category == ACTORCAT_EXPLOSIVES) && (params->player->stateFlags1 & PLAYER_STATE1_200))) &&
                     params->canFreezeCategory && (actor != params->talkActor) && (actor != params->player->heldActor) &&
                     (actor->parent != &params->player->actor))) {
@@ -2605,7 +2604,7 @@ Actor* Actor_UpdateActor(UpdateActor_Params* params) {
             actor->yawTowardsPlayer = Actor_WorldYawTowardActor(actor, &params->player->actor);
             actor->flags &= ~ACTOR_FLAG_SFX_FOR_PLAYER_BODY_HIT;
 
-            if ((DECR(actor->freezeTimer) == 0) && (actor->flags & params->unk_18)) {
+            if ((DECR(actor->freezeTimer) == 0) && (actor->flags & params->updateActorFlagsMask)) {
                 if (actor == params->player->focusActor) {
                     actor->isLockedOn = true;
                 } else {
@@ -2677,10 +2676,11 @@ void Actor_UpdateAll(PlayState* play, ActorContext* actorCtx) {
     params.player = player;
     params.play = play;
 
-    if (play->unk_18844) {
-        params.unk_18 = ACTOR_FLAG_200000;
+    if (play->soaringCsOrSoTCsPlaying) {
+        params.updateActorFlagsMask = ACTOR_FLAG_UPDATE_DURING_SOARING_AND_SOT_CS;
     } else {
-        params.unk_18 = ACTOR_FLAG_200000 | ACTOR_FLAG_INSIDE_CULLING_VOLUME | ACTOR_FLAG_UPDATE_CULLING_DISABLED;
+        params.updateActorFlagsMask = ACTOR_FLAG_UPDATE_DURING_SOARING_AND_SOT_CS | ACTOR_FLAG_INSIDE_CULLING_VOLUME |
+                                      ACTOR_FLAG_UPDATE_CULLING_DISABLED;
     }
 
     Actor_SpawnSetupActors(play, actorCtx);
@@ -3136,13 +3136,14 @@ void Actor_DrawAll(PlayState* play, ActorContext* actorCtx) {
     Gfx* sp58;
     ActorListEntry* actorEntry;
     Actor* actor;
-    s32 actorFlags;
+    s32 drawActorFlagsMask;
     s32 category;
 
-    if (play->unk_18844) {
-        actorFlags = ACTOR_FLAG_200000;
+    if (play->soaringCsOrSoTCsPlaying) {
+        drawActorFlagsMask = ACTOR_FLAG_UPDATE_DURING_SOARING_AND_SOT_CS;
     } else {
-        actorFlags = ACTOR_FLAG_200000 | ACTOR_FLAG_INSIDE_CULLING_VOLUME | ACTOR_FLAG_DRAW_CULLING_DISABLED;
+        drawActorFlagsMask = ACTOR_FLAG_UPDATE_DURING_SOARING_AND_SOT_CS | ACTOR_FLAG_INSIDE_CULLING_VOLUME |
+                             ACTOR_FLAG_DRAW_CULLING_DISABLED;
     }
 
     OPEN_DISPS(play->state.gfxCtx);
@@ -3170,7 +3171,7 @@ void Actor_DrawAll(PlayState* play, ActorContext* actorCtx) {
             }
 
             actor->isDrawn = false;
-            if ((actor->init == NULL) && (actor->draw != NULL) && (actor->flags & actorFlags)) {
+            if ((actor->init == NULL) && (actor->draw != NULL) && (actor->flags & drawActorFlagsMask)) {
                 if ((actor->flags & ACTOR_FLAG_REACT_TO_LENS) &&
                     ((play->roomCtx.curRoom.lensMode == LENS_MODE_SHOW_ACTORS) ||
                      (play->actorCtx.lensMaskSize == LENS_MASK_ACTIVE_SIZE) ||
@@ -3212,7 +3213,7 @@ void Actor_DrawAll(PlayState* play, ActorContext* actorCtx) {
     gSPBranchList(ref2, &tmp2[1]);
     POLY_XLU_DISP = &tmp2[1];
 
-    if (!play->unk_18844) {
+    if (!play->soaringCsOrSoTCsPlaying) {
         Lights_DrawGlow(play);
     }
 
diff --git a/src/code/z_eventmgr.c b/src/code/z_eventmgr.c
index 1b0b8aea1..218ebadc5 100644
--- a/src/code/z_eventmgr.c
+++ b/src/code/z_eventmgr.c
@@ -215,7 +215,7 @@ void CutsceneManager_End(void) {
 
     switch (sCutsceneMgr.startMethod) {
         case CS_START_2:
-            sCutsceneMgr.targetActor->flags &= ~ACTOR_FLAG_100000;
+            sCutsceneMgr.targetActor->flags &= ~ACTOR_FLAG_FREEZE_EXCEPTION;
             FALLTHROUGH;
         case CS_START_1:
             Player_SetCsActionWithHaltedActors(sCutsceneMgr.play, NULL, PLAYER_CSACTION_END);
@@ -359,7 +359,7 @@ s16 CutsceneManager_StartWithPlayerCs(s16 csId, Actor* actor) {
 }
 
 /**
- * Start an actor cutscene, activate Player Cutscene Action "Wait", turn on ACTOR_FLAG_100000
+ * Start an actor cutscene, activate Player Cutscene Action "Wait", turn on ACTOR_FLAG_FREEZE_EXCEPTION
  */
 s16 CutsceneManager_StartWithPlayerCsAndSetFlag(s16 csId, Actor* actor) {
     s16 startCsId = CutsceneManager_Start(csId, actor);
@@ -370,7 +370,7 @@ s16 CutsceneManager_StartWithPlayerCsAndSetFlag(s16 csId, Actor* actor) {
             CutsceneManager_Stop(sCutsceneMgr.csId);
         }
         if (actor != NULL) {
-            actor->flags |= ACTOR_FLAG_100000;
+            actor->flags |= ACTOR_FLAG_FREEZE_EXCEPTION;
             sCutsceneMgr.startMethod = CS_START_2;
         } else {
             sCutsceneMgr.startMethod = CS_START_1;
diff --git a/src/code/z_play.c b/src/code/z_play.c
index ae387114f..9ed00afb1 100644
--- a/src/code/z_play.c
+++ b/src/code/z_play.c
@@ -1277,7 +1277,7 @@ void Play_DrawMain(PlayState* this) {
                 goto PostWorldDraw;
             }
 
-            if (!this->unk_18844) {
+            if (!this->soaringCsOrSoTCsPlaying) {
                 if (1) {
                     if (((u32)this->skyboxId != SKYBOX_NONE) && !this->envCtx.skyboxDisabled) {
                         if ((this->skyboxId == SKYBOX_NORMAL_SKY) || (this->skyboxId == SKYBOX_3)) {
@@ -2270,7 +2270,7 @@ void Play_Init(GameState* thisx) {
     this->worldCoverAlpha = 0;
     this->bgCoverAlpha = 0;
     this->haltAllActors = false;
-    this->unk_18844 = false;
+    this->soaringCsOrSoTCsPlaying = false;
 
     if (gSaveContext.gameMode != GAMEMODE_TITLE_SCREEN) {
         if (gSaveContext.nextTransitionType == TRANS_NEXT_TYPE_DEFAULT) {
diff --git a/src/code/z_player_call.c b/src/code/z_player_call.c
index 9eb191dc9..bc559b3de 100644
--- a/src/code/z_player_call.c
+++ b/src/code/z_player_call.c
@@ -3,8 +3,8 @@
 
 #define FLAGS                                                                                  \
     (ACTOR_FLAG_ATTENTION_ENABLED | ACTOR_FLAG_FRIENDLY | ACTOR_FLAG_UPDATE_CULLING_DISABLED | \
-     ACTOR_FLAG_DRAW_CULLING_DISABLED | ACTOR_FLAG_200000 | ACTOR_FLAG_UPDATE_DURING_OCARINA | \
-     ACTOR_FLAG_CAN_PRESS_SWITCHES | ACTOR_FLAG_MINIMAP_ICON_ENABLED)
+     ACTOR_FLAG_DRAW_CULLING_DISABLED | ACTOR_FLAG_UPDATE_DURING_SOARING_AND_SOT_CS |          \
+     ACTOR_FLAG_UPDATE_DURING_OCARINA | ACTOR_FLAG_CAN_PRESS_SWITCHES | ACTOR_FLAG_MINIMAP_ICON_ENABLED)
 
 ActorFunc sPlayerCallInitFunc;
 ActorFunc sPlayerCallDestroyFunc;
diff --git a/src/code/z_player_lib.c b/src/code/z_player_lib.c
index 1f27a4702..81bb0cb77 100644
--- a/src/code/z_player_lib.c
+++ b/src/code/z_player_lib.c
@@ -1961,7 +1961,7 @@ void Player_AdjustSingleLeg(PlayState* play, Player* player, SkelAnime* skelAnim
     f32 sp7C;
 
     if ((player->stateFlags3 & PLAYER_STATE3_1) || !(player->actor.scale.y >= 0.0f) ||
-        (player->stateFlags1 & PLAYER_STATE1_DEAD) || play->unk_18844) {
+        (player->stateFlags1 & PLAYER_STATE1_DEAD) || play->soaringCsOrSoTCsPlaying) {
         return;
     }