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 106cb1021b, 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>

include/save.h

@@ -401,6 +401,7 @@ typedef enum SceneLayer {
 } SceneLayer;
 
 #define IS_CUTSCENE_LAYER (gSaveContext.sceneLayer >= SCENE_LAYER_CUTSCENE_FIRST)
+#define GET_CUTSCENE_LAYER(index) (SCENE_LAYER_CUTSCENE_FIRST + (index & 0xF))
 
 typedef enum LinkAge {
     /* 0 */ LINK_AGE_ADULT,
@@ -408,6 +409,53 @@ typedef enum LinkAge {
 } LinkAge;
 
 
+// Usage in Map Select suggests that `gSaveContext.save.cutsceneIndex` was,
+// at one point in development, a variable related to the time.
+// This is further supported by debug strings showing that its original name was "day_time".
+// These macros exist for the rare cases in the codebase where `cutsceneIndex` is treated as a time value.
+// In practice, both values do not lead to a cutscene being played.
+// See `CS_INDEX_NONE` below for the more common usage of value 0x0000.
+#define CS_INDEX_NIGHT 0x0000
+#define CS_INDEX_DAY 0x8000
+
+// Indicates that no scripted cutscene is playing (or should be played).
+// While this value overlaps with `CS_INDEX_NIGHT` defined above, it is not related to the time.
+// This is the more common interpretation of this value, as much of the codebase uses 0x0000 to mean "no cutscene"
+// except for Map Select.
+#define CS_INDEX_NONE 0x0000
+
+// Values 0xFFF0-0xFFFF indicate that a cutscene script should be played.
+// If the value of `nextCutsceneIndex` is 0xFFF0-0xFFFF on scene load,
+// `Play_Init` will copy the value to `gSaveContext.cutsceneIndex`, load a
+// corresponding scene layer and start the scripted cutscene in the scene layer
+// (except for the value 0xFFFD, which is special-cased to do nothing in `Play_Init`).
+// It loads layer 4 for 0xFFF0, layer 5 for 0xFFF1, and so on.
+//
+// 0xFFFD is used by the cutscene system to indicate a scripted cutscene has been triggered.
+// This is why `Play_Init` ignores that value, so that if the cutscene is interrupted
+// by a new play state load (e.g. if the player falls out of bounds), it does not then
+// try to wrongly load a cutscene layer.
+#define CS_INDEX_0 0xFFF0
+#define CS_INDEX_1 0xFFF1
+#define CS_INDEX_2 0xFFF2
+#define CS_INDEX_3 0xFFF3
+#define CS_INDEX_4 0xFFF4
+#define CS_INDEX_5 0xFFF5
+#define CS_INDEX_6 0xFFF6
+#define CS_INDEX_7 0xFFF7
+#define CS_INDEX_8 0xFFF8
+#define CS_INDEX_9 0xFFF9
+#define CS_INDEX_A 0xFFFA
+#define CS_INDEX_B 0xFFFB
+#define CS_INDEX_C 0xFFFC
+#define CS_INDEX_D 0xFFFD // does not load a cutscene scene layer (see above)
+#define CS_INDEX_E 0xFFFE
+#define CS_INDEX_F 0xFFFF
+
+// Sentinel value for `nextCutsceneIndex` to indicate that no cutscene should be played next.
+#define NEXT_CS_INDEX_NONE 0xFFEF
+
+
 #define LINK_IS_ADULT (gSaveContext.save.linkAge == LINK_AGE_ADULT)
 #define LINK_IS_CHILD (gSaveContext.save.linkAge == LINK_AGE_CHILD)