z_demo documentation (#1327)

* commit old stuff

* progress

* progress

* progress

* progress

* more progress, renaming cues next

* small changes

* enum values added for all actions

* hardcoded values removed when possible

* commands renamed

* first pass of action -> cue

* fix some matches

* some more cleanup

* scriptPtr

* forgot one

* remove cue rot union

* more changes

* some more stuff

* more stuff

* fix matching issues

* some more things

* progress, starting to rename destinations

* small changes

* name some destinations

* more names

* need to switch branch

* progress

* first pass of destination names

* usages fixed

* use destination enum

* fix csdis

* format

* command descriptions

* revert accidental zap changes

* forgot some things

* use a single macro for CutsceneCameraPoint (idk why i didnt think of this sooner)

* typo

* review1

* clarify ruby/sapphire comment

* remove endframe for commands that dont use it

* some more review

* most review, but not all

* scriptPtr -> script, and another small change

* ocarina action

* remove +1 from light settings command, change comment

* actionIndex -> cueIdTemp (i guess)

* _SetCueX -> _SetXFromCue

* format

* tweak fade out seq arg names

* use spline terminology

* more dragorn and engineer review

* misc start/end frame note

* cleanup StartPosRotFromCue vs PosRotFromCue

* cleanup spline terminology

* sPrevCamId -> sReturnToCamId

* comment on debug cs data address

* Cutscene_Init -> Cutscene_InitContext

* single point types are not a list

* remove todo comment

* some more review

* rumble struct names

* some review

* more review

* missed one

* reword pointer comment

* even more review

* match transition terminology with z_play

* change condition and format

* frame count

* command specific structs with alignment

* anon review

* remove unneeded arg from time macro

* yeet `CsCmdGeneric`

* remove unused from single point types

* typo

* compromise attempt -- name endFrame everywhere

* fixes

* fix again

* copied the wrong note

* cutscene data note

* review, format

* compat defines

* idk whats going on man

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

src/code/z_play.c

@@ -2,17 +2,17 @@
 #include "quake.h"
 #include "terminal.h"
 
-void* D_8012D1F0 = NULL;
+void* gDebugCutsceneScript = NULL;
 UNK_TYPE D_8012D1F4 = 0; // unused
 Input* D_8012D1F8 = NULL;
 
 TransitionUnk sTrnsnUnk;
 s32 gTrnsnUnkState;
 VisMono D_80161498;
-Color_RGBA8_u32 D_801614B0;
+Color_RGBA8_u32 gVisMonoColor;
 FaultClient D_801614B8;
 s16 sTransitionFillTimer;
-u64 D_801614D0[0xA00];
+u64 sDebugCutsceneScriptBuf[0xA00];
 
 void Play_SpawnScene(PlayState* this, s32 sceneId, s32 spawn);
 
@@ -266,7 +266,7 @@ void Play_Init(GameState* thisx) {
     EffectSs_InitInfo(this, 0x55);
     CollisionCheck_InitContext(this, &this->colChkCtx);
     AnimationContext_Reset(&this->animationCtx);
-    func_8006450C(this, &this->csCtx);
+    Cutscene_InitContext(this, &this->csCtx);
 
     if (gSaveContext.nextCutsceneIndex != 0xFFEF) {
         gSaveContext.cutsceneIndex = gSaveContext.nextCutsceneIndex;
@@ -371,7 +371,7 @@ void Play_Init(GameState* thisx) {
     this->transitionTrigger = TRANS_TRIGGER_END;
     this->unk_11E16 = 0xFF;
     this->unk_11E18 = 0;
-    this->unk_11DE9 = false;
+    this->haltAllActors = false;
 
     if (gSaveContext.gameMode != GAMEMODE_TITLE_SCREEN) {
         if (gSaveContext.nextTransitionType == TRANS_NEXT_TYPE_DEFAULT) {
@@ -391,8 +391,8 @@ void Play_Init(GameState* thisx) {
     TransitionFade_SetColor(&this->transitionFadeFlash, RGBA8(160, 160, 160, 255));
     TransitionFade_Start(&this->transitionFadeFlash);
     VisMono_Init(&D_80161498);
-    D_801614B0.a = 0;
-    Flags_UnsetAllEnv(this);
+    gVisMonoColor.a = 0;
+    CutsceneFlags_UnsetAll(this);
 
     osSyncPrintf("ZELDA ALLOC SIZE=%x\n", THA_GetRemaining(&this->state.tha));
     zAllocSize = THA_GetRemaining(&this->state.tha);
@@ -436,10 +436,13 @@ void Play_Init(GameState* thisx) {
     AnimationContext_Update(this, &this->animationCtx);
     gSaveContext.respawnFlag = 0;
 
-    if (dREG(95) != 0) {
-        D_8012D1F0 = D_801614D0;
-        osSyncPrintf("\nkawauso_data=[%x]", D_8012D1F0);
-        DmaMgr_DmaRomToRam(0x03FEB000, D_8012D1F0, sizeof(D_801614D0));
+    if (R_USE_DEBUG_CUTSCENE) {
+        gDebugCutsceneScript = sDebugCutsceneScriptBuf;
+        osSyncPrintf("\nkawauso_data=[%x]", gDebugCutsceneScript);
+
+        // This hardcoded ROM address extends past the end of the ROM file.
+        // Presumably the ROM was larger at a previous point in development when this debug feature was used.
+        DmaMgr_DmaRomToRam(0x03FEB000, gDebugCutsceneScript, sizeof(sDebugCutsceneScriptBuf));
     }
 }
 
@@ -888,15 +891,15 @@ void Play_Update(PlayState* this) {
 
                     PLAY_LOG(3637);
 
-                    if (!this->unk_11DE9) {
+                    if (!this->haltAllActors) {
                         Actor_UpdateAll(this, &this->actorCtx);
                     }
 
                     PLAY_LOG(3643);
-                    func_80064558(this, &this->csCtx);
+                    Cutscene_UpdateManual(this, &this->csCtx);
 
                     PLAY_LOG(3648);
-                    func_800645A0(this, &this->csCtx);
+                    Cutscene_UpdateScripted(this, &this->csCtx);
 
                     PLAY_LOG(3651);
                     Effect_UpdateAll(this);
@@ -1096,8 +1099,8 @@ void Play_Draw(PlayState* this) {
 
             TransitionFade_Draw(&this->transitionFadeFlash, &gfxP);
 
-            if (D_801614B0.a > 0) {
-                D_80161498.primColor.rgba = D_801614B0.rgba;
+            if (gVisMonoColor.a > 0) {
+                D_80161498.primColor.rgba = gVisMonoColor.rgba;
                 VisMono_Draw(&D_80161498, &gfxP);
             }