Player Cutscenes (csMode)

Anything detailed in this doc was figured out by myself and tharo going back and forth in a DM.

Link has a system for performing actions that are typically associated with cutscnes. Going forward it'll be important to distinguish between the different types of cutscenes.

When I refer to a "scripted cutscene", I am talking about a cutscene that is executed by running commands. For those in the speedrunning community, you are familiar with these as cutscenes that set the "cutscene pointer".

When I refer to a "player cutscene", I am talking about short actions/animations that link does. These are not scripted cutscenes, but they invoked by a scripted cutscene.

---

There are two arrays that are going to be important here: `D_80854B18` and `D_80854E50`. The structure of the data in these arrays are as follows:

typedef struct {
    /* 0x00 */ s8 type;
    /* 0x04 */ union {
        void* ptr;
        void (*func)(GlobalContext*, Player*, CsCmdActorAction*);
    };
} struct_80854B18; // size = 0x08

type needs a bit more research, and is not too important for what I'm talking about here.
The second field can either be a function pointer, or some arbitrary data. If type is -1, it will treat whatever is there as a function.
Otherwise it uses whatever data is provided. Passing an animation pointer is common.

There are two arrays because one is ran only one time, intended to "set up" the upcoming cutscene. The second is ran every frame as an "update".
`D_80854B18` contains the setup list, and `D_80854E50` contains the update list.

---
How player cutscenes are invoked:

In z_actor.c there is a function: `func_8002DF54`
This gets called many times throughout the codebase and takes a few args:
global context, an actor pointer, and an index. NULL is valid for an actor pointer, as long as the cutscene being called does not expect an actor to work properly. Don't expect the cutscene actions to error check this for you.

From here on, the index into this function will be referred to as `csMode`.

After csMode is set by `func_8002DF54`, player is constantly checking if his current csMode is the same as the last csMode. This check is performed in `func_80852E14`.
If the current csMode and previous csMode do not match, this means the action was changed. When this is true, the setup array mentioned earlier is used. `D_80854B18` gets indexed by the csMode number. If the data pointer is an animation, it will set links animation to that value. If its a function, it will run the function (which usually has a bit more involved setup).

Outside of the if block checking for the changed csMode, this function is also indexing the update array. This happens unconditionally every frame, unlike the setup info. Typically these update modes contain a function, which then calls skelanime_update and whatever else may be required every frame. The master sword cutscene for example uses an update function that does specific things on specific animation frames via code.

-

Now, for the elephant in the room. What do scripted cutscenes have to do with this system?
Scripted cutscenes interface with player cutscenes a bit indirectly. A scripted cutscene provides a action number via its cutscene commands in the script. This action number is NOT the same as a csMode index.

The way this was implemented is kind of interesting. csMode 6 specifically is used internally by link for scripted cutscenes. If link sees a non-null actor action, he will invoke csMode 6 on his own. Index 6 in the setup array is null, so no setup is performed. Then it calls the update function which is `func_80852C50`.
`func_80852C50` itself will handle scripted cutscene specific behavior, which includes calling the setup and update functions AGAIN, but with a new index provided by the cutscene command.

To reiterate the process of executing a scripted cutscene action:
Link sees an actor action pointer -> csMode 6 is invoked, which runs the update function -> the update function runs the setup and update functions AGAIN, but with a new index provided by the script.

To make things more confusing, the index provided by the cutscene command does NOT correspond to the indices used for the setup and update arrays.
Instead, it passes the action index provided by the script into an array `D_808547C4` which will then give you the proper index to be used for setup and update.
The indices in this array can be positive or negative. More in depth research to understand this needs to be done. But positive indices seem to have extra logic that runs to see if the player has reached a specified point.

To give a practical example, lets step through how a scripted cutscene will make link walk:
- A scripted cutscene is playing
- A cutscene command in the script sets `globalCtx->csCtx.linkAction`
- Link sees that this value is not null. Immediately calls `func_8002DF54` to set csMode to 6 (scripted cs mode)
- csMode 6 has no init function, but has an update.
- The update function indexes `D_808547C4` with the action number provided by the linkAction. For walking this index is 2. 3 is returned from the array
- Index 3 recieved from the array is used to call the third setup and update func. Since 3 is a positive number, it will do the special handling related to making sure link is near the specified point from the cutscene command.

---

What does this mean for me as the programmer?
This system requires that you know the implementation details of each action to be able to use it properly. You need to know if the given csMode index will call any functions that require either an actor pointer or a cutscene command to be present.
You can technically call any of these csModes outside of a scripted cutscnene, but if you use one that expects a scripted cutscene to be playing you will crash.

At minimum, only those indices listed in D_808547C4 will require a scripted cutscene to be playing. Some of them listed here will not, but any action numbers *not* present here are safe to use outside of a script.

For details on what each csMode index does, I've started a page that I am maintaining here: https://docs.google.com/spreadsheets/d/12RpxLB-AhiilGi6aG7MNKia2lhkAKivjly9V8GL-utg/edit?ts=607f77bf#gid=1431542613

Others in the community are doing interesting player docs on other pages.