name event group flags

include/enums.h

@@ -3462,7 +3462,7 @@ enum FirstStrikeType {
 };
 
 enum TimeFreezeMode {
-    TIME_FREEZE_NORMAL          = 0,
+    TIME_FREEZE_NONE            = 0,
     TIME_FREEZE_PARTIAL         = 1,
     TIME_FREEZE_FULL            = 2,
     TIME_FREEZE_POPUP_MENU      = 3,

include/evt.h

@@ -125,29 +125,38 @@ enum EventCommandResults {
     EVT_CMD_RESULT_ERROR        = 1,
 };
 
+// EventGroupFlags define categories that determine when a script is paused and resumed.
+// Scripts are assigned groups consisting of flag combinations to only pause in certain circumstances.
+// These group flags are inherited when one script launches another.
 enum EventGroupFlags {
-    EVT_GROUP_00    = 0x00,
-    EVT_GROUP_0A    = 0x0A, // 8 | 2
-    EVT_GROUP_0B    = 0x0B, // 8 | 4 | 1
-    EVT_GROUP_1B    = 0x1B, // EVT_GOUP_EXIT_MAP? 10 | 8 | 4 | 1
-    EVT_GROUP_EF    = 0xEF, // ~10
-    EVT_GROUP_01    = 0x01,
-    EVT_GROUP_02    = 0x02,
-    EVT_GROUP_SHAKE_CAM    = 0x04,
-    EVT_GROUP_08    = 0x08,
-    EVT_GROUP_10    = 0x10,
+    // Each flag represents a distinct condition for suspending or resuming script execution.
+    // These flags are named based on the scenarios that trigger suspension.
+    EVT_GROUP_FLAG_INTERACT = 0x01, // Suspended during certain scenes, interactions, and NPC dialogue.
+    EVT_GROUP_FLAG_MENUS    = 0x02, // Suspended when menus are open, during pause, item pickups, or "got item" scenes.
+    EVT_GROUP_FLAG_CAM      = 0x04, // Never suspended; used exclusively with camera shake (ShakeCam) scripts.
+    EVT_GROUP_FLAG_UNUSED   = 0x08, // Unused flag; its original purpose is unknown.
+    EVT_GROUP_FLAG_BATTLE   = 0x10, // Suspended during battle entry and exit transitions.
+
+    // Combinations of flags used to assign specific behaviors to scripts.
+    // These groups are named after their most common use-cases.
+    EVT_GROUP_NEVER_PAUSE   = 0x00, // Never paused; default for map scripts derived from the main script, which always uses this group.
+    EVT_GROUP_PASSIVE_NPC   = EVT_GROUP_FLAG_MENUS | EVT_GROUP_FLAG_UNUSED, // 0xA -- Pauses similar to passive NPC scripts.
+    EVT_GROUP_HOSTILE_NPC   = EVT_GROUP_FLAG_INTERACT | EVT_GROUP_FLAG_MENUS | EVT_GROUP_FLAG_UNUSED, // 0xB -- Pauses similar to hostile NPC scripts; used for platforms, machinery, etc.
+    EVT_GROUP_EXIT_MAP      = EVT_GROUP_FLAG_INTERACT | EVT_GROUP_FLAG_MENUS | EVT_GROUP_FLAG_UNUSED | EVT_GROUP_FLAG_BATTLE, // 0x1B -- Used for exit map scripts.
+    EVT_GROUP_SHAKE_CAM     = EVT_GROUP_FLAG_CAM, // Only used by ShakeCam scripts.
+    EVT_GROUP_NOT_BATTLE    = 0xFF & ~EVT_GROUP_FLAG_BATTLE, // 0xEF -- Pauses from anything except battles; default for scripts started via start_script, common in many battle scripts.
 };
 
 enum EventPriority {
-    EVT_PRIORITY_0  = 0x00, // map main script
-    EVT_PRIORITY_1  = 0x01,
-    EVT_PRIORITY_A  = 0x0A,
-    EVT_PRIORITY_14 = 0x14,
+    EVT_PRIORITY_0          = 0x00, // map main script
+    EVT_PRIORITY_1          = 0x01,
+    EVT_PRIORITY_A          = 0x0A,
+    EVT_PRIORITY_14         = 0x14,
 };
 
 enum EventStateFlags {
     EVT_FLAG_ACTIVE             = 0x01,
-    EVT_FLAG_SUSPENDED_IN_GROUP = 0x02,
+    EVT_FLAG_PAUSED             = 0x02, ///< paused through suspend_group_script / resume_group_script
     EVT_FLAG_BLOCKED_BY_CHILD   = 0x10,
     EVT_FLAG_RUN_IMMEDIATELY    = 0x20, ///< don't wait for next `update_scripts` call
     EVT_FLAG_THREAD             = 0x40,

include/script_api/macros.h

@@ -659,7 +659,7 @@
 
 #define EVT_EXIT_WALK(walkDistance, exitIdx, map, entryIdx) \
     { \
-        SetGroup(EVT_GROUP_1B) \
+        SetGroup(EVT_GROUP_EXIT_MAP) \
         Call(UseExitHeading, walkDistance, exitIdx) \
         Exec(ExitWalk) \
         Call(GotoMap, Ref(map), entryIdx) \
@@ -668,7 +668,7 @@
         End \
     }
 
-// alternate version of EVT_EXIT_WALK used on Pleasant Path which does not join EVT_GROUP_1B
+// alternate version of EVT_EXIT_WALK used on Pleasant Path which does not join EVT_GROUP_EXIT_MAP
 #define EVT_EXIT_WALK_NOK(walkDistance, exitIdx, map, entryIdx) \
     { \
         Call(UseExitHeading, walkDistance, exitIdx) \
@@ -682,7 +682,7 @@
 // alternate version of EVT_EXIT_WALK which includes a call to DisablePlayerInput
 #define EVT_EXIT_WALK_FIXED(walkDistance, exitIdx, map, entryIdx) \
     { \
-        SetGroup(EVT_GROUP_1B) \
+        SetGroup(EVT_GROUP_EXIT_MAP) \
         Call(DisablePlayerInput, TRUE) \
         Call(UseExitHeading, walkDistance, exitIdx) \
         Exec(ExitWalk) \
@@ -694,7 +694,7 @@
 
 #define EVT_EXIT_SINGLE_DOOR(exitIdx, map, entryIdx, colliderID, modelID, swingDir) \
     { \
-        SetGroup(EVT_GROUP_1B) \
+        SetGroup(EVT_GROUP_EXIT_MAP) \
         Call(DisablePlayerInput, TRUE) \
         Set(LVar0, exitIdx) \
         Set(LVar1, colliderID) \
@@ -710,7 +710,7 @@
 
 #define EVT_EXIT_SPLIT_SINGLE_DOOR(exitIdx, map, entryIdx, colliderID, topModelID, bottomModelID, swingDir) \
     { \
-        SetGroup(EVT_GROUP_1B) \
+        SetGroup(EVT_GROUP_EXIT_MAP) \
         Call(DisablePlayerInput, TRUE) \
         Set(LVar0, exitIdx) \
         Set(LVar1, colliderID) \
@@ -727,7 +727,7 @@
 
 #define EVT_EXIT_DOUBLE_DOOR(exitIdx, map, entryIdx, colliderID, leftDoorModelID, rightDoorModelID) \
     { \
-        SetGroup(EVT_GROUP_1B) \
+        SetGroup(EVT_GROUP_EXIT_MAP) \
         Call(DisablePlayerInput, TRUE) \
         Set(LVar0, exitIdx) \
         Set(LVar1, colliderID) \

include/variables.h

@@ -93,7 +93,7 @@ extern Vec3s StandardActorHomePositions[];
 extern SaveData gCurrentSaveFile;
 
 extern s32 gEncounterSubState;
-extern s32 timeFreezeMode;
+extern s32 gTimeFreezeMode;
 extern b32 EncounterStateChanged;
 
 extern u8 IntroMessageIdx;

src/111f0_len_860.c

@@ -40,7 +40,7 @@ void init_enter_world_shared(void) {
     gOverrideFlags |= GLOBAL_OVERRIDES_DISABLE_DRAW_FRAME;
 
     evt_set_variable(NULL, GB_Unused_EVT_01, gGameStatusPtr->unk_A9);
-    timeFreezeMode = 0;
+    gTimeFreezeMode = TIME_FREEZE_NONE;
 }
 
 void state_step_enter_world(void) {
@@ -61,7 +61,7 @@ void state_step_enter_world(void) {
             }
 
             gGameStatusPtr->prevArea = gGameStatusPtr->areaID;
-            set_time_freeze_mode(TIME_FREEZE_NORMAL);
+            set_time_freeze_mode(TIME_FREEZE_NONE);
             if (gGameStatusPtr->demoState == DEMO_STATE_NONE) {
                 disable_player_input();
             }
@@ -158,7 +158,7 @@ void state_step_change_map(void) {
                 gGameStatusPtr->context = CONTEXT_WORLD;
                 gGameStatusPtr->debugScripts = DEBUG_SCRIPTS_NONE;
                 load_map_by_IDs(gGameStatusPtr->areaID, gGameStatusPtr->mapID, LOAD_FROM_MAP);
-                set_time_freeze_mode(TIME_FREEZE_NORMAL);
+                set_time_freeze_mode(TIME_FREEZE_NONE);
                 nuContRmbForceStopEnd();
                 if (gGameStatusPtr->demoState == DEMO_STATE_NONE) {
                     disable_player_input();

src/battle/area/trd_part_2/actor/fake_bowser.c

@@ -450,7 +450,7 @@ EvtScript N(EVS_AnimBowser_DeathMain) = {
     UseArray(FakeBowserAnimState)
     Call(N(StartRumbleWithParams), 256, 30)
     Thread
-        SetGroup(EVT_GROUP_00)
+        SetGroup(EVT_GROUP_NEVER_PAUSE)
         Call(ShakeCam, CAM_BATTLE, 0, 20, Float(3.0))
     EndThread
     Call(SetPartFlagBits, ACTOR_SELF, PRT_HEAD, ACTOR_PART_FLAG_USE_ABSOLUTE_POSITION, TRUE)
@@ -476,48 +476,48 @@ EvtScript N(EVS_AnimBowser_DeathMain) = {
     Wait(30)
     Call(PlaySoundAtModel, MODEL_k1, SOUND_DISTANT_THUD, SOUND_SPACE_DEFAULT)
     Thread
-        SetGroup(EVT_GROUP_00)
+        SetGroup(EVT_GROUP_NEVER_PAUSE)
         Call(ShakeCam, CAM_BATTLE, 0, 5, Float(1.0))
     EndThread
     Call(N(StartRumbleWithParams), 100, 20)
     Wait(20)
     Call(PlaySoundAtModel, MODEL_u1, SOUND_DISTANT_THUD, SOUND_SPACE_DEFAULT)
     Thread
-        SetGroup(EVT_GROUP_00)
+        SetGroup(EVT_GROUP_NEVER_PAUSE)
         Call(ShakeCam, CAM_BATTLE, 0, 10, Float(1.5))
     EndThread
     Call(N(StartRumbleWithParams), 150, 20)
     Wait(30)
     Call(PlaySoundAtModel, MODEL_p1, SOUND_DISTANT_THUD, SOUND_SPACE_DEFAULT)
     Thread
-        SetGroup(EVT_GROUP_00)
+        SetGroup(EVT_GROUP_NEVER_PAUSE)
         Call(ShakeCam, CAM_BATTLE, 0, 10, Float(1.0))
     EndThread
     Call(N(StartRumbleWithParams), 100, 20)
     Wait(30)
     Call(PlaySoundAtModel, MODEL_d1, SOUND_DISTANT_THUD, SOUND_SPACE_DEFAULT)
     Thread
-        SetGroup(EVT_GROUP_00)
+        SetGroup(EVT_GROUP_NEVER_PAUSE)
         Call(ShakeCam, CAM_BATTLE, 0, 5, Float(0.7))
     EndThread
     Call(N(StartRumbleWithParams), 70, 20)
     Wait(20)
     Call(PlaySoundAtModel, MODEL_s1, SOUND_DISTANT_THUD, SOUND_SPACE_DEFAULT)
     Thread
-        SetGroup(EVT_GROUP_00)
+        SetGroup(EVT_GROUP_NEVER_PAUSE)
         Call(ShakeCam, CAM_BATTLE, 0, 10, Float(1.0))
     EndThread
     Call(N(StartRumbleWithParams), 100, 20)
     Wait(20)
     Call(PlaySoundAtModel, MODEL_km1, SOUND_DISTANT_THUD, SOUND_SPACE_DEFAULT)
     Call(N(StartRumbleWithParams), 60, 20)
     Thread
-        SetGroup(EVT_GROUP_00)
+        SetGroup(EVT_GROUP_NEVER_PAUSE)
         Call(ShakeCam, CAM_BATTLE, 0, 5, Float(0.6))
     EndThread
     Wait(20)
     Thread
-        SetGroup(EVT_GROUP_00)
+        SetGroup(EVT_GROUP_NEVER_PAUSE)
         Call(ShakeCam, CAM_BATTLE, 0, 5, Float(0.3))
     EndThread
     Call(N(StartRumbleWithParams), 30, 20)

src/bss/main_pre_bss.c

@@ -27,7 +27,7 @@ BSS s32 gEncounterSubState;
 BSS u32 __osBbRCountWraps;
 #endif
 BSS void *CurrentSefCmdHandler;
-BSS s32 timeFreezeMode;
+BSS s32 gTimeFreezeMode;
 #ifdef BBPLAYER
 BSS u32 __osBbLastRCount;
 #endif

src/encounter.c

@@ -1173,7 +1173,7 @@ void update_encounters_neutral(void) {
             gEncounterSubState = ENCOUNTER_SUBSTATE_PRE_BATTLE_INIT;
             break;
         case ENCOUNTER_TRIGGER_CONVERSATION:
-            suspend_all_group(EVT_GROUP_01);
+            suspend_all_group(EVT_GROUP_FLAG_INTERACT);
             enemy = currentEncounter->curEnemy;
             if (enemy != NULL && enemy->aiScript != NULL) {
                 suspend_all_script(enemy->aiScriptID);
@@ -1276,7 +1276,7 @@ void update_encounters_pre_battle(void) {
             currentEncounter->unk_08 = -1;
             HasPreBattleSongPushed = FALSE;
             D_80077C40 = FALSE;
-            suspend_all_group(EVT_GROUP_10);
+            suspend_all_group(EVT_GROUP_FLAG_BATTLE);
 
             // suspend all ai scripts
             for (i = 0; i < currentEncounter->numEncounters; i++) {
@@ -1674,7 +1674,7 @@ void update_encounters_post_battle(void) {
             if (currentEncounter->hasMerleeCoinBonus) {
                 if (get_coin_drop_amount(currentEncounter->curEnemy) != 0) {
                     MerleeDropCoinsEvt = start_script(&EVS_MerleeDropCoins, EVT_PRIORITY_A, 0);
-                    MerleeDropCoinsEvt->groupFlags = EVT_GROUP_00;
+                    MerleeDropCoinsEvt->groupFlags = EVT_GROUP_NEVER_PAUSE;
                     MerleeDropCoinsEvtID = MerleeDropCoinsEvt->id;
                 } else {
                     playerData->merleeTurnCount = 0;
@@ -1711,20 +1711,20 @@ void update_encounters_post_battle(void) {
                     continue;
                 }
                 if (enemy->defeatBytecode != NULL) {
-                    script = start_script_in_group(enemy->defeatBytecode, EVT_PRIORITY_A, 0, 0);
+                    script = start_script_in_group(enemy->defeatBytecode, EVT_PRIORITY_A, 0, EVT_GROUP_NEVER_PAUSE);
                     enemy->defeatScript = script;
                     enemy->defeatScriptID = script->id;
                     script->owner1.enemy = enemy;
                     script->owner2.npcID = enemy->npcID;
-                    script->groupFlags = EVT_GROUP_00;
+                    script->groupFlags = EVT_GROUP_NEVER_PAUSE;
                     currentEncounter->battleStartCountdown = 1;
                 } else {
-                    script = start_script_in_group(&EVS_NpcDefeat, EVT_PRIORITY_A, 0, 0);
+                    script = start_script_in_group(&EVS_NpcDefeat, EVT_PRIORITY_A, 0, EVT_GROUP_NEVER_PAUSE);
                     enemy->defeatScript = script;
                     enemy->defeatScriptID = script->id;
                     script->owner1.enemy = enemy;
                     script->owner2.npcID = enemy->npcID;
-                    script->groupFlags = EVT_GROUP_00;
+                    script->groupFlags = EVT_GROUP_NEVER_PAUSE;
                 }
             }
             if (!(currentEncounter->flags & ENCOUNTER_FLAG_THUMBS_UP)
@@ -1844,7 +1844,7 @@ void update_encounters_post_battle(void) {
                 suggest_player_anim_allow_backward(ANIM_Mario1_Idle);
             }
             set_screen_overlay_params_front(OVERLAY_NONE, -1.0f);
-            resume_all_group(EVT_GROUP_10);
+            resume_all_group(EVT_GROUP_FLAG_BATTLE);
             gEncounterState = ENCOUNTER_STATE_NEUTRAL;
             EncounterStateChanged = TRUE;
             gEncounterSubState = ENCOUNTER_SUBSTATE_NEUTRAL;
@@ -1976,7 +1976,7 @@ void update_encounters_post_battle(void) {
             if (!PendingPartnerAbilityResume && playerStatus->anim == ANIM_MarioB3_Hustled) {
                 suggest_player_anim_allow_backward(ANIM_Mario1_Idle);
             }
-            resume_all_group(EVT_GROUP_10);
+            resume_all_group(EVT_GROUP_FLAG_BATTLE);
             gEncounterState = ENCOUNTER_STATE_NEUTRAL;
             EncounterStateChanged = TRUE;
             gEncounterSubState = ENCOUNTER_SUBSTATE_NEUTRAL;
@@ -2068,7 +2068,7 @@ void update_encounters_post_battle(void) {
                     break;
                 }
             }
-            resume_all_group(EVT_GROUP_10);
+            resume_all_group(EVT_GROUP_FLAG_BATTLE);
             gEncounterState = ENCOUNTER_STATE_NEUTRAL;
             EncounterStateChanged = TRUE;
             gEncounterSubState = ENCOUNTER_SUBSTATE_NEUTRAL;
@@ -2096,7 +2096,7 @@ void update_encounters_post_battle(void) {
             enable_player_input();
             partner_enable_input();
             set_screen_overlay_params_front(OVERLAY_NONE, -1.0f);
-            resume_all_group(EVT_GROUP_10);
+            resume_all_group(EVT_GROUP_FLAG_BATTLE);
             gEncounterState = ENCOUNTER_STATE_NEUTRAL;
             EncounterStateChanged = TRUE;
             gEncounterSubState = ENCOUNTER_SUBSTATE_NEUTRAL;
@@ -2199,7 +2199,7 @@ void update_encounters_post_battle(void) {
                 enable_player_input();
                 partner_enable_input();
                 set_screen_overlay_params_front(OVERLAY_NONE, -1.0f);
-                resume_all_group(EVT_GROUP_10);
+                resume_all_group(EVT_GROUP_FLAG_BATTLE);
                 gEncounterState = ENCOUNTER_STATE_NEUTRAL;
                 EncounterStateChanged = TRUE;
                 gEncounterSubState = ENCOUNTER_SUBSTATE_NEUTRAL;
@@ -2274,7 +2274,7 @@ void update_encounters_conversation(void) {
             }
             break;
         case ENCOUNTER_SUBSTATE_CONVERSATION_END:
-            resume_all_group(EVT_GROUP_01);
+            resume_all_group(EVT_GROUP_FLAG_INTERACT);
 
             currentEnemy = encounter->curEnemy;
             if (currentEnemy != NULL && currentEnemy->aiScript != NULL) {
@@ -2290,7 +2290,7 @@ void update_encounters_conversation(void) {
 
             func_800EF3D4(0);
             encounter->hitType = 0;
-            resume_all_group(EVT_GROUP_10);
+            resume_all_group(EVT_GROUP_FLAG_BATTLE);
             gEncounterState = ENCOUNTER_STATE_NEUTRAL;
             EncounterStateChanged = TRUE;
             gEncounterSubState = ENCOUNTER_SUBSTATE_NEUTRAL;
@@ -2646,9 +2646,9 @@ void create_encounters(void) {
                     if (enemy->flags & ENEMY_FLAG_DONT_UPDATE_SHADOW_Y) {
                         newNpc->flags |= NPC_FLAG_DONT_UPDATE_SHADOW_Y;
                     }
-                    enemy->scriptGroup = EVT_GROUP_0B;
+                    enemy->scriptGroup = EVT_GROUP_HOSTILE_NPC;
                     if (enemy->flags & ENEMY_FLAG_PASSIVE) {
-                        enemy->scriptGroup = EVT_GROUP_0A;
+                        enemy->scriptGroup = EVT_GROUP_PASSIVE_NPC;
                     }
                     if (npcSettings->otherAI != NULL) {
                         script = start_script(npcSettings->otherAI, EVT_PRIORITY_A, 0);
@@ -2786,7 +2786,7 @@ void create_encounters(void) {
                     }
                 }
             }
-            resume_all_group(EVT_GROUP_10);
+            resume_all_group(EVT_GROUP_FLAG_BATTLE);
             gEncounterState = ENCOUNTER_STATE_NEUTRAL;
             EncounterStateChanged = TRUE;
             gEncounterSubState = ENCOUNTER_SUBSTATE_NEUTRAL;