Document `Save.cutsceneIndex` and adjacent data / code (#2286)

* introduce `enum CutsceneIndex` as a first step

* crudely rename `enum CutsceneIndex` entries

* run `check_format.py ...` separetely

so that it doesn't clutter previous commit. still, allowing `clangd LSP` to run format-on-save yields inconsistent results for me with the project's tooling, especially for header files

* apply a draft PR suggestion

Co-authored-by: mzxrules <mzxrules@gmail.com>

* rename `CS_INDEX_*` with PR suggestions

and some additional observations
reverified with
> `check_format.py ...`
> `make ...`

additionally:
- current clang-format lacks a rule for trailing commas
- compiler says about them `cfe: Warning 624`

* improve `CS_INDEX_*` naming, rem `ENTRANCE` suffix

https://github.com/zeldaret/oot/pull/2286#discussion_r1829165205

reverified with
> `check_format.py ...`
> `make ...`

* apply Jenkins fixes

https://jenkins.deco.mp/job/OOT/job/PR-2286/4/console

hmm, i do need this automation locally to

* apply a PR suggestion

https://github.com/zeldaret/oot/pull/2286#discussion_r1829219841

* remove redundant comments, fix the header comment

and add a comment chunk from https://github.com/zeldaret/oot/pull/2286#discussion_r1829108940

* rename the flag for freeing `nextCutsceneIndex`

* rename the flag for automatic `sceneLayer` calc

it gets assigned to the `nextCutsceneIndex`,
so `CS_INDEX_NONE` name was misleading

* use explicit scene layer names instead of numbers

* ok, now the last two `CS_INDEX_*` are less unknown

the purpose of `CS_INDEX_BARRIER` is not quite clear still

* apply Jenkins fixes

https://jenkins.deco.mp/job/OOT/job/PR-2286/14/console

* run `fix_bss` locally

`ntsc-1.2` refused to comply though

* revert all local to the branch bss shifts

* ugh, use defines instead of an enum

probably size of enum entries doesn't match well? originally these were
just numbers. besides, not like it's a real enumeration from zero to a
value or some bit flags

* still, add a BSS pragma for `z_demo.c`

* apply review changes

* factor out a cutscene layer formula

* give scene layers names throughout code

* apply Jenkins fixes

https://jenkins.deco.mp/job/OOT/job/PR-2286/32/console

* tweak `CS_INDEX` descriptions

* apply PR review suggestions

* rename "auto" -> "default"

* apply PR review suggestions

https://github.com/zeldaret/oot/pull/2286#discussion_r1868693980

essentially reverts 106cb1021be88f745ee303838c11c7d7cbf9c79d, except for 2 generic `z_scene.c` lines

* apply Jenkins fixes

https://jenkins.deco.mp/job/OOT/job/PR-2286/77/console

* Apply suggestions from code review

Co-authored-by: Dragorn421 <Dragorn421@users.noreply.github.com>
Co-authored-by: mzxrules <mzxrules@gmail.com>

* apply Jenkins fixes

https://jenkins.deco.mp/job/OOT/job/PR-2286/175/console

* Move CS_INDEX_* macros to z64save.h, with the definition of gSaveContext.save.cutsceneIndex

* `#define CS_INDEX_D 0xFFFD` and co.

Co-authored-by: cadmic <cadmic24@gmail.com>

* add comment on CS_INDEX_D

* review

* CS_INDEX_NONE is back

* bss

* expand comment about 0xFFFD

* fix comment about 0xFFFF usage

* review

---------

Co-authored-by: mzxrules <mzxrules@gmail.com>
Co-authored-by: Dragorn421 <Dragorn421@users.noreply.github.com>
Co-authored-by: cadmic <cadmic24@gmail.com>

1 files changed, 4 insertions, 4 deletions

diff --git a/src/code/z_parameter.c b/src/code/z_parameter.c
index fa8ec09c5..1709031cf 100644
--- a/src/code/z_parameter.c
+++ b/src/code/z_parameter.c
@@ -670,8 +670,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_0) ||
+        ((play->sceneId == SCENE_LON_LON_RANCH) && (gSaveContext.save.cutsceneIndex == CS_INDEX_0))) {
         gSaveContext.forceRisingButtonAlphas = false;
 
         if ((player->stateFlags1 & PLAYER_STATE1_23) || (play->shootingGalleryStatus > 1) ||
@@ -3554,7 +3554,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;
@@ -3884,7 +3884,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 {