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, 2 insertions, 2 deletions

diff --git a/src/code/z_sram.c b/src/code/z_sram.c
index 17bfb5baa..c1a514a94 100644
--- a/src/code/z_sram.c
+++ b/src/code/z_sram.c
@@ -859,11 +859,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_1;
 
 #if DEBUG_FEATURES
     if (fileSelect->buttonIndex == 0) {
-        gSaveContext.save.cutsceneIndex = 0;
+        gSaveContext.save.cutsceneIndex = CS_INDEX_NONE;
     }
 #endif