Document Save.cutsceneIndex and adjacent data / code

include/z64cutscene.h

@@ -344,6 +344,42 @@ typedef enum CutsceneDestination {
     /* 0x77 */ CS_DEST_ZELDAS_COURTYARD_RECEIVE_LETTER
 } CutsceneDestination;
 
+/*
+correlation with `enum SceneLayer`:
+  CS_INDEX_MANUAL:     [SCENE_LAYER_CHILD_DAY .. SCENE_LAYER_ADULT_NIGHT]
+  CS_INDEX_SCRIPTED_*: SCENE_LAYER_CUTSCENE_FIRST
+
+correlation with `enum EntranceIndex`
+  CS_INDEX_MANUAL:     base entrance index + scene layer
+  CS_INDEX_SCRIPTED_*: base entrance index + SCENE_LAYER_CUTSCENE_FIRST + (cutscene index & 0xF)
+
+`z_select.c` naming:
+  CS_INDEX_NONE:       "Stage: night"
+  CS_INDEX_LAST:       "Stage: day"
+  CS_INDEX_SCRIPTED_*: "Stage demo 0*", between [0xFFF0 .. 0xFFFA]
+*/
+typedef enum CutsceneIndex {
+    CS_INDEX_NONE = 0x0000,
+    CS_INDEX_MANUAL = 0xFFEF,
+    CS_INDEX_SCRIPTED_0 = 0xFFF0,
+    CS_INDEX_SCRIPTED_1 = 0xFFF1,
+    CS_INDEX_SCRIPTED_2 = 0xFFF2,
+    CS_INDEX_SCRIPTED_3 = 0xFFF3,
+    CS_INDEX_SCRIPTED_4 = 0xFFF4,
+    CS_INDEX_SCRIPTED_5 = 0xFFF5,
+    CS_INDEX_SCRIPTED_6 = 0xFFF6,
+    CS_INDEX_SCRIPTED_7 = 0xFFF7,
+    CS_INDEX_SCRIPTED_8 = 0xFFF8,
+    CS_INDEX_SCRIPTED_9 = 0xFFF9,
+    CS_INDEX_SCRIPTED_A = 0xFFFA,
+    CS_INDEX_SCRIPTED_B = 0xFFFB,
+    CS_INDEX_SCRIPTED_C = 0xFFFC,
+    CS_INDEX_SCRIPTED_D = 0xFFFD,
+    CS_INDEX_SCRIPTED_E = 0xFFFE,
+    CS_INDEX_SCRIPTED_F = 0xFFFF,
+    CS_INDEX_LAST = 0x8000,
+} CutsceneIndex;
+
 typedef union CsCmdCam {
     struct {
         /* 0x00 */ u16 unused0;

src/code/db_camera.c

@@ -2185,7 +2185,7 @@ s32 DebugCamera_UpdateDemoControl(DebugCam* debugCam, Camera* cam) {
 
             if (CHECK_BTN_ALL(sPlay->state.input[1].press.button, BTN_CRIGHT)) {
                 gUseCutsceneCam = false;
-                gSaveContext.save.cutsceneIndex = 0xFFFD;
+                gSaveContext.save.cutsceneIndex = CS_INDEX_SCRIPTED_D;
                 gSaveContext.cutsceneTrigger = 1;
                 sDebugCamAnim.curFrame = 0.0f;
                 sDebugCamAnim.keyframe = 0;

src/code/z_common_data.c

@@ -16,7 +16,7 @@ void SaveContext_Init(void) {
     gSaveContext.seqId = (u8)NA_BGM_DISABLED;
     gSaveContext.natureAmbienceId = NATURE_ID_DISABLED;
     gSaveContext.forcedSeqId = NA_BGM_GENERAL_SFX;
-    gSaveContext.nextCutsceneIndex = 0xFFEF;
+    gSaveContext.nextCutsceneIndex = CS_INDEX_MANUAL;
     gSaveContext.cutsceneTrigger = 0;
     gSaveContext.chamberCutsceneNum = CHAMBER_CS_FOREST;
     gSaveContext.nextDayTime = NEXT_TIME_NONE;

src/code/z_horse.c

@@ -192,7 +192,7 @@ void func_8006D684(PlayState* play, Player* player) {
                 (((void)0, gSaveContext.save.cutsceneIndex) == D_8011F9B8[i].cutsceneIndex)) {
                 if (D_8011F9B8[i].type == 7) {
                     if ((play->sceneId == SCENE_LON_LON_RANCH) &&
-                        (((void)0, gSaveContext.save.cutsceneIndex) == 0xFFF1)) {
+                        (((void)0, gSaveContext.save.cutsceneIndex) == CS_INDEX_SCRIPTED_1)) {
                         D_8011F9B8[i].pos.x = player->actor.world.pos.x;
                         D_8011F9B8[i].pos.y = player->actor.world.pos.y;
                         D_8011F9B8[i].pos.z = player->actor.world.pos.z;

src/code/z_kaleido_setup.c

@@ -66,9 +66,9 @@ void KaleidoSetup_Update(PlayState* play) {
 
     if (!IS_PAUSED(pauseCtx) && play->gameOverCtx.state == GAMEOVER_INACTIVE &&
         play->transitionTrigger == TRANS_TRIGGER_OFF && play->transitionMode == TRANS_MODE_OFF &&
-        gSaveContext.save.cutsceneIndex < 0xFFF0 && gSaveContext.nextCutsceneIndex < 0xFFF0 && !Play_InCsMode(play) &&
-        play->shootingGalleryStatus <= 1 && gSaveContext.magicState != MAGIC_STATE_STEP_CAPACITY &&
-        gSaveContext.magicState != MAGIC_STATE_FILL &&
+        gSaveContext.save.cutsceneIndex < CS_INDEX_SCRIPTED_0 && gSaveContext.nextCutsceneIndex < CS_INDEX_SCRIPTED_0 &&
+        !Play_InCsMode(play) && play->shootingGalleryStatus <= 1 &&
+        gSaveContext.magicState != MAGIC_STATE_STEP_CAPACITY && gSaveContext.magicState != MAGIC_STATE_FILL &&
         (play->sceneId != SCENE_BOMBCHU_BOWLING_ALLEY || !Flags_GetSwitch(play, 0x38))) {
 
         if (CHECK_BTN_ALL(input->cur.button, BTN_L) && CHECK_BTN_ALL(input->press.button, BTN_CUP)) {

src/code/z_kankyo.c

@@ -2618,7 +2618,7 @@ void Environment_StopStormNatureAmbience(PlayState* play) {
 
 void Environment_WarpSongLeave(PlayState* play) {
     gWeatherMode = WEATHER_MODE_CLEAR;
-    gSaveContext.save.cutsceneIndex = 0;
+    gSaveContext.save.cutsceneIndex = CS_INDEX_NONE;
     gSaveContext.respawnFlag = -3;
     play->nextEntranceIndex = gSaveContext.respawn[RESPAWN_MODE_RETURN].entranceIndex;
     play->transitionTrigger = TRANS_TRIGGER_START;

src/code/z_message.c

@@ -4294,7 +4294,7 @@ void Message_Update(PlayState* play) {
 
                     if (msgCtx->textId != 0x2061 && msgCtx->textId != 0x2025 && msgCtx->textId != 0x208C &&
                         ((msgCtx->textId < 0x88D || msgCtx->textId >= 0x893) || msgCtx->choiceIndex != 0) &&
-                        (msgCtx->textId != 0x3055 && gSaveContext.save.cutsceneIndex < 0xFFF0)) {
+                        (msgCtx->textId != 0x3055 && gSaveContext.save.cutsceneIndex < CS_INDEX_SCRIPTED_0)) {
                         PRINTF("=== day_time=%x ", ((void)0, gSaveContext.save.cutsceneIndex));
                         if (play->activeCamId == CAM_ID_MAIN) {
                             if (gSaveContext.prevHudVisibilityMode == HUD_VISIBILITY_NO_CHANGE ||

src/code/z_parameter.c

@@ -644,8 +644,8 @@ void func_80083108(PlayState* play) {
     s16 i;
     s16 sp28 = false;
 
-    if ((gSaveContext.save.cutsceneIndex < 0xFFF0) ||
-        ((play->sceneId == SCENE_LON_LON_RANCH) && (gSaveContext.save.cutsceneIndex == 0xFFF0))) {
+    if ((gSaveContext.save.cutsceneIndex < CS_INDEX_SCRIPTED_0) ||
+        ((play->sceneId == SCENE_LON_LON_RANCH) && (gSaveContext.save.cutsceneIndex == CS_INDEX_SCRIPTED_0))) {
         gSaveContext.forceRisingButtonAlphas = false;
 
         if ((player->stateFlags1 & PLAYER_STATE1_23) || (play->shootingGalleryStatus > 1) ||
@@ -3523,7 +3523,7 @@ void Interface_Draw(PlayState* play) {
             (Message_GetState(&play->msgCtx) == TEXT_STATE_EVENT)) {
             // Trade quest timer reached 0
             sSubTimerStateTimer = 40;
-            gSaveContext.save.cutsceneIndex = 0;
+            gSaveContext.save.cutsceneIndex = CS_INDEX_NONE;
             play->transitionTrigger = TRANS_TRIGGER_START;
             play->transitionType = TRANS_TYPE_FADE_WHITE;
             gSaveContext.subTimerState = SUBTIMER_STATE_OFF;
@@ -3861,7 +3861,7 @@ void Interface_Draw(PlayState* play) {
                                                  (play->sceneId != SCENE_INSIDE_GANONS_CASTLE_COLLAPSE))) {
                                                 sSubTimerStateTimer = 40;
                                                 gSaveContext.subTimerState = SUBTIMER_STATE_RESPAWN;
-                                                gSaveContext.save.cutsceneIndex = 0;
+                                                gSaveContext.save.cutsceneIndex = CS_INDEX_NONE;
                                                 Message_StartTextbox(play, 0x71B0, NULL);
                                                 Player_SetCsActionWithHaltedActors(play, NULL, PLAYER_CSACTION_8);
                                             } else {

src/code/z_play.c

@@ -55,7 +55,8 @@ void Play_SetViewpoint(PlayState* this, s16 viewpoint) {
 
     this->viewpoint = viewpoint;
 
-    if ((R_SCENE_CAM_TYPE != SCENE_CAM_TYPE_FIXED_SHOP_VIEWPOINT) && (gSaveContext.save.cutsceneIndex < 0xFFF0)) {
+    if ((R_SCENE_CAM_TYPE != SCENE_CAM_TYPE_FIXED_SHOP_VIEWPOINT) &&
+        (gSaveContext.save.cutsceneIndex < CS_INDEX_SCRIPTED_0)) {
         // Play a sfx when the player toggles the camera
         Audio_PlaySfxGeneral((viewpoint == VIEWPOINT_LOCKED) ? NA_SE_SY_CAMERA_ZOOM_DOWN : NA_SE_SY_CAMERA_ZOOM_UP,
                              &gSfxDefaultPos, 4, &gSfxDefaultFreqAndVolScale, &gSfxDefaultFreqAndVolScale,
@@ -324,13 +325,13 @@ void Play_Init(GameState* thisx) {
     AnimTaskQueue_Reset(&this->animTaskQueue);
     Cutscene_InitContext(this, &this->csCtx);
 
-    if (gSaveContext.nextCutsceneIndex != 0xFFEF) {
+    if (gSaveContext.nextCutsceneIndex != CS_INDEX_MANUAL) {
         gSaveContext.save.cutsceneIndex = gSaveContext.nextCutsceneIndex;
-        gSaveContext.nextCutsceneIndex = 0xFFEF;
+        gSaveContext.nextCutsceneIndex = CS_INDEX_MANUAL;
     }
 
-    if (gSaveContext.save.cutsceneIndex == 0xFFFD) {
-        gSaveContext.save.cutsceneIndex = 0;
+    if (gSaveContext.save.cutsceneIndex == CS_INDEX_SCRIPTED_D) {
+        gSaveContext.save.cutsceneIndex = CS_INDEX_NONE;
     }
 
     if (gSaveContext.nextDayTime != NEXT_TIME_NONE) {
@@ -346,7 +347,7 @@ void Play_Init(GameState* thisx) {
 
     Cutscene_HandleConditionalTriggers(this);
 
-    if (gSaveContext.gameMode != GAMEMODE_NORMAL || gSaveContext.save.cutsceneIndex >= 0xFFF0) {
+    if (gSaveContext.gameMode != GAMEMODE_NORMAL || gSaveContext.save.cutsceneIndex >= CS_INDEX_SCRIPTED_0) {
         gSaveContext.nayrusLoveTimer = 0;
         Magic_Reset(this);
         gSaveContext.sceneLayer = SCENE_LAYER_CUTSCENE_FIRST + (gSaveContext.save.cutsceneIndex & 0xF);
@@ -596,7 +597,7 @@ void Play_Update(PlayState* this) {
 
                         Interface_ChangeHudVisibilityMode(HUD_VISIBILITY_NOTHING);
 
-                        if (gSaveContext.save.cutsceneIndex >= 0xFFF0) {
+                        if (gSaveContext.save.cutsceneIndex >= CS_INDEX_SCRIPTED_0) {
                             sceneLayer = SCENE_LAYER_CUTSCENE_FIRST + (gSaveContext.save.cutsceneIndex & 0xF);
                         }
 

src/code/z_scene.c

@@ -382,7 +382,7 @@ BAD_RETURN(s32) Scene_CommandTimeSettings(PlayState* play, SceneCmd* cmd) {
     play->envCtx.sunPos.y = (Math_CosS(((void)0, gSaveContext.save.dayTime) - CLOCK_TIME(12, 0)) * 120.0f) * 25.0f;
     play->envCtx.sunPos.z = (Math_CosS(((void)0, gSaveContext.save.dayTime) - CLOCK_TIME(12, 0)) * 20.0f) * 25.0f;
 
-    if (((play->envCtx.sceneTimeSpeed == 0) && (gSaveContext.save.cutsceneIndex < 0xFFF0)) ||
+    if (((play->envCtx.sceneTimeSpeed == 0) && (gSaveContext.save.cutsceneIndex < CS_INDEX_SCRIPTED_0)) ||
         (gSaveContext.save.entranceIndex == ENTR_LAKE_HYLIA_8)) {
 #if OOT_VERSION >= PAL_1_0
         gSaveContext.skyboxTime = ((void)0, gSaveContext.save.dayTime);
@@ -488,7 +488,7 @@ BAD_RETURN(s32) Scene_CommandMiscSettings(PlayState* play, SceneCmd* cmd) {
 
     if (((play->sceneId >= SCENE_HYRULE_FIELD) && (play->sceneId <= SCENE_OUTSIDE_GANONS_CASTLE)) ||
         ((play->sceneId >= SCENE_MARKET_ENTRANCE_DAY) && (play->sceneId <= SCENE_TEMPLE_OF_TIME_EXTERIOR_RUINS))) {
-        if (gSaveContext.save.cutsceneIndex < 0xFFF0) {
+        if (gSaveContext.save.cutsceneIndex < CS_INDEX_SCRIPTED_0) {
             gSaveContext.save.info.worldMapAreaData |= gBitFlags[((void)0, gSaveContext.worldMapArea)];
             PRINTF("０００  ａｒｅａ＿ａｒｒｉｖａｌ＝%x (%d)\n", gSaveContext.save.info.worldMapAreaData,
                    ((void)0, gSaveContext.worldMapArea));

src/code/z_sram.c

@@ -793,11 +793,11 @@ void Sram_InitSave(FileSelectState* fileSelect, SramContext* sramCtx) {
     gSaveContext.save.entranceIndex = ENTR_LINKS_HOUSE_0;
     gSaveContext.save.linkAge = LINK_AGE_CHILD;
     gSaveContext.save.dayTime = CLOCK_TIME(10, 0);
-    gSaveContext.save.cutsceneIndex = 0xFFF1;
+    gSaveContext.save.cutsceneIndex = CS_INDEX_SCRIPTED_1;
 
 #if OOT_DEBUG
     if (fileSelect->buttonIndex == 0) {
-        gSaveContext.save.cutsceneIndex = 0;
+        gSaveContext.save.cutsceneIndex = CS_INDEX_NONE;
     }
 #endif
 

src/overlays/actors/ovl_Bg_Ingate/z_bg_ingate.c

@@ -45,7 +45,7 @@ void BgInGate_Init(Actor* thisx, PlayState* play) {
     this->dyna.bgId = DynaPoly_SetBgActor(play, &play->colCtx.dyna, &this->dyna.actor, colHeader);
 
     if ((play->sceneId != SCENE_LON_LON_RANCH || !LINK_IS_ADULT) ||
-        (GET_EVENTCHKINF(EVENTCHKINF_EPONA_OBTAINED) && (gSaveContext.save.cutsceneIndex != 0xFFF0))) {
+        (GET_EVENTCHKINF(EVENTCHKINF_EPONA_OBTAINED) && (gSaveContext.save.cutsceneIndex != CS_INDEX_SCRIPTED_0))) {
         Actor_Kill(&this->dyna.actor);
         return;
     }

src/overlays/actors/ovl_Bg_Relay_Objects/z_bg_relay_objects.c

@@ -108,7 +108,8 @@ void BgRelayObjects_Destroy(Actor* thisx, PlayState* play) {
     BgRelayObjects* this = (BgRelayObjects*)thisx;
 
     DynaPoly_DeleteBgActor(play, &play->colCtx.dyna, this->dyna.bgId);
-    if ((this->dyna.actor.params == WINDMILL_ROTATING_GEAR) && (gSaveContext.save.cutsceneIndex < 0xFFF0)) {
+    if ((this->dyna.actor.params == WINDMILL_ROTATING_GEAR) &&
+        (gSaveContext.save.cutsceneIndex < CS_INDEX_SCRIPTED_0)) {
         CLEAR_EVENTCHKINF(EVENTCHKINF_65);
     }
 }

src/overlays/actors/ovl_Bg_Spot00_Hanebasi/z_bg_spot00_hanebasi.c

@@ -217,7 +217,7 @@ void BgSpot00Hanebasi_Update(Actor* thisx, PlayState* play) {
                     this->actionFunc = BgSpot00Hanebasi_DoNothing;
                     Player_SetCsActionWithHaltedActors(play, &player->actor, PLAYER_CSACTION_8);
                     play->nextEntranceIndex = ENTR_HYRULE_FIELD_0;
-                    gSaveContext.nextCutsceneIndex = 0xFFF1;
+                    gSaveContext.nextCutsceneIndex = CS_INDEX_SCRIPTED_1;
                     play->transitionTrigger = TRANS_TRIGGER_START;
                     play->transitionType = TRANS_TYPE_FADE_BLACK_FAST;
                 } else if (Actor_IsFacingAndNearPlayer(&this->dyna.actor, 3000.0f, 0x7530)) {

src/overlays/actors/ovl_Boss_Ganon2/z_boss_ganon2.c

@@ -2104,7 +2104,7 @@ void func_8090120C(BossGanon2* this, PlayState* play) {
             FALLTHROUGH;
         case 20:
             play->nextEntranceIndex = ENTR_CHAMBER_OF_THE_SAGES_0;
-            gSaveContext.nextCutsceneIndex = 0xFFF2;
+            gSaveContext.nextCutsceneIndex = CS_INDEX_SCRIPTED_2;
             play->transitionTrigger = TRANS_TRIGGER_START;
             play->transitionType = TRANS_TYPE_FADE_WHITE;
             play->linkAgeOnLoad = LINK_AGE_CHILD;